当前位置：首页 > news >正文

java servlet: context-path的作用

news 来源：原创 2025/6/3 13:16:22

当没有配置 java servlet: context-path 时， swagger的地址是

http://localhost:8086/api/v1/swagger-ui/index.html

当配置了 java servlet: context-path 时， swagger的地址前要加上context-path

比如 application.yml是

server:port: 8086servlet:context-path: /api/v1/spring:datasource:url: jdbc:mysql://localhost:3306/user_db?useSSL=false&serverTimezone=UTC&characterEncoding=utf8username: rootpassword: rootdriver-class-name: com.mysql.cj.jdbc.Drivertype: com.alibaba.druid.pool.DruidDataSourcedruid:initial-size: 5min-idle: 5max-active: 20test-while-idle: truetest-on-borrow: falsetest-on-return: falsemybatis-plus:configuration:log-impl: org.apache.ibatis.logging.stdout.StdOutImplmap-underscore-to-camel-case: trueglobal-config:db-config:id-type: autologic-delete-field: deletedlogic-delete-value: 1logic-not-delete-value: 0springdoc:swagger-ui:path: /swagger-ui.htmltags-sorter: alphaoperations-sorter: alpha

`context-path` 的作用（Spring Boot 中的 `server.servlet.context-path`）

context-path（上下文路径）是 Web 应用的基础路径，用于区分不同的应用或模块。在 Spring Boot 中，可以通过 server.servlet.context-path 配置项来设置。

1. 主要作用

(1) 提供应用隔离

如果同一个 Tomcat 服务器部署多个应用，可以通过不同的 context-path 区分它们。
示例：
- http://localhost:8080/app1/ → 应用1
- http://localhost:8080/app2/ → 应用2

(2) 统一 API 前缀

所有 API 自动加上 context-path 前缀，避免手动在每个 @RequestMapping 中重复写路径。
示例：
yaml

复制
server: servlet: context-path: /api
- 访问 /api/users 而不是 /users

(3) 适配代理服务器（Nginx/Apache）

反向代理（如 Nginx）可以通过 context-path 将请求转发到不同的微服务。
示例：
复制
location /api/ { proxy_pass http://localhost:8080/api/; }

2. 配置方式

(1) `application.properties` / `application.yml`

yaml

复制

server: servlet: context-path: /api # 所有请求需加 /api 前缀

生效后：

http://localhost:8080/api/test → 实际访问 /test 接口

(2) 代码方式（不推荐）

java

复制

@SpringBootApplication public class MyApp { public static void main(String[] args) { SpringApplication app = new SpringApplication(MyApp.class); app.setDefaultProperties(Collections.singletonMap("server.servlet.context-path", "/api")); app.run(args); } }

3. 影响范围

所有请求（包括静态资源、API、WebSocket）都会自动加上 context-path 前缀。
示例：
- 静态资源：/api/index.html（原路径 /static/index.html）
- API 接口：/api/users（原路径 /users）
- WebSocket：/api/ws（原路径 /ws）
特殊情况：
- @RequestMapping 已经包含 /api，则最终路径会是 /api/api/xxx（需注意避免重复）。

4. 常见问题

(1) 静态资源 404

如果配置了 context-path，访问静态资源时也要加上前缀：

复制

http://localhost:8080/api/css/style.css

解决方案：

确保静态资源放在 src/main/resources/static/ 下
前端代码引用资源时使用相对路径或动态拼接 context-path

(2) Swagger/Actuator 路径变化

Swagger UI：http://localhost:8080/api/swagger-ui.html
Actuator：http://localhost:8080/api/actuator/health

(3) 测试时路径错误

在单元测试中，MockMvc 需要手动处理 context-path：

java

复制

@SpringBootTest @AutoConfigureMockMvc class MyControllerTest { @Autowired private MockMvc mockMvc; @Test void testApi() throws Exception { mockMvc.perform(get("/api/test")) // 必须带上 /api .andExpect(status().isOk()); } }

5. 最佳实践

微服务推荐使用 /api 作为默认前缀，避免直接暴露根路径。
前端代码动态获取 context-path（避免硬编码）：
javascript

复制
const API_BASE = window.location.pathname.split('/')[1] || ''; fetch(`/${API_BASE}/users`);
结合 @RequestMapping 使用：
java

复制
@RestController @RequestMapping("/v1") // 最终路径: /api/v1/users public class UserController { @GetMapping("/users") public List<User> getUsers() { ... } }

总结

场景	说明
多应用隔离	不同应用使用不同 `context-path`
统一 API 前缀	避免手动写 `/api` 前缀
反向代理适配	Nginx/Apache 根据路径转发请求
静态资源访问	需加上 `context-path`