在 Spring Boot 中定义“服务上线前缀”（即统一 URL 前缀）有多种实现路径，本质属于 请求路径规范化（API Namespacing）。
1. 基础方式：全局 Context Path（推荐基础方案）
这是最直接、最常用的方式，相当于给整个服务加一层统一前缀。
1.1 配置方式
1
2
3
| server:
servlet:
context-path: /api
|
1.2 效果
1
2
| 原路径: /user/list
实际访问: /api/user/list
|
1.3 特点
| 维度 |
说明 |
| 生效范围 |
全局 |
| 实现层 |
Servlet 容器层（Tomcat） |
| 侵入性 |
低 |
| 推荐场景 |
单体服务 / 简单微服务 |
2. Controller 层统一前缀（业务分层推荐）
通过 Controller 层定义模块前缀，实现更细粒度控制。
2.1 示例
1
2
3
4
5
6
7
8
9
| @RestController
@RequestMapping("/api/user")
public class UserController {
@GetMapping("/list")
public String list() {
return "ok";
}
}
|
2.2 特点
- 灵活（可按模块划分）
- 不影响其他服务路径
- 常用于：
1
2
3
| /api/user/*
/api/order/*
/api/admin/*
|
适用于 统一规范 + 自动化治理（SRE/平台化）
3.1 实现方式
1
2
3
4
5
6
7
8
9
10
| @Configuration
public class WebConfig implements WebMvcConfigurer {
@Override
public void configurePathMatch(PathMatchConfigurer configurer) {
configurer.addPathPrefix("/api", clazz ->
clazz.isAnnotationPresent(RestController.class)
);
}
}
|
3.2 特点
| 维度 |
说明 |
| 控制粒度 |
精确（可按注解控制） |
| 侵入性 |
无需改 Controller |
| 可扩展性 |
强（适合平台化） |
4. 网关层统一前缀
在微服务体系中，不建议在服务内部硬编码前缀，而是交由网关统一处理。
本质：url rewrite
4.1 常见方案
- Spring Cloud Gateway
- Nginx
- APISIX / Kong
4.2 Spring Cloud Gateway 示例
1
2
3
4
5
6
7
8
9
10
| spring:
cloud:
gateway:
routes:
- id: user-service
uri: lb://user-service
predicates:
- Path=/api/user/**
filters:
- StripPrefix=1
|
4.3 特点
| 维度 |
说明 |
| 解耦 |
强 |
| 统一治理 |
强（限流、鉴权、灰度） |
| 推荐等级 |
⭐⭐⭐⭐⭐ |
5. 多环境/版本前缀（企业级实践）
5.1 常见规范
1
2
3
| /api/v1/user
/api/v2/user
/internal/api/user
|
5.2 实现方式
方式1：context-path
1
2
3
| server:
servlet:
context-path: /api/v1
|
方式2：Controller
1
| @RequestMapping("/api/v1/user")
|
方式3：网关（推荐）
6. 最佳实践（SRE/架构视角）
6.1 推荐分层
flowchart TB
A[Client] --> B[Gateway]
B --> C[Service]
B -->|/api/v1/*| C
C -->|内部路径 /user/*| D[Controller]
6.2 设计原则
前缀统一放在网关层（最佳）
服务内部只关注业务路径（去前缀化）
使用版本号隔离 API（v1/v2）
内外接口分离：
/api/*（外部）/internal/*（内部）
7. 结论
| 场景 |
推荐方案 |
| 单体应用 |
context-path |
| 中小系统 |
Controller + 规范 |
| 微服务 |
网关统一前缀（核心推荐） |
| 平台化治理 |
WebMvcConfigurer |
| 多版本API |
网关 + version |