- 接口URL规范
【强制】命名规范:采用RESTful风格，使用小写字母，单词之间使用短横线连接，如 /user/get-user-info。
【建议】版本管理: 在URL中包含版本号，如 /v1/user/get-user-info.
【强制】环境标识: 对于不同环境（开发、测试、生产），使用环境标识，如 /dev/v1/user/get-user-info.
【建议】微服务开发时，URL应包括微服务名称作为前缀，例如：/dev/v1/user-service/user/profile。
- 接口命名规范
【强制】RESTful风格：使用有意义的名词，遵循驼峰命名规范。
【强制】资源命名: 使用名词表示资源，尽量使用复数形式，如 /users, /products.
【强制】请求方式：涵盖资源的基本操作，如增删改查，可以使用标准的HTTP方法（GET、POST、PUT、DELETE）来表示。
GET请求: 用于获取资源，参数通过URL传递。
POST请求: 用于创建资源，参数通过请求体传递，格式为JSON。
PUT请求: 用于更新资源，参数通过请求体传递，格式为JSON。
DELETE请求: 用于删除资源，参数通过URL传递。
- 入参规范
【强制】POST、PUT请求统一使用JSON格式作为请求体。
【建议】对于GET、DELETE请求，可以将参数放在URL中，使用?分隔，多个参数使用&连接。
- 出参规范
【强制】统一使用JSON格式作为响应体。
【强制】返回的JSON对象应包含必要的元数据，如状态码、消息等。
【强制】采用统一的响应结构。
{
"code": 200,
"message": "成功",
"data": { /* 实际数据 */ }
}
出参状态码规范：
200：成功
201：资源创建成功
204：资源删除成功
400：请求参数错误
401：未授权
403：禁止访问
404：资源不存在
500：服务器内部错误
用户自定义状态码应避免与HTTP标准状态码冲突，建议使用大于等于1000的数值。
| 格式 | 状态码区间 | 模块 |
|---|---|---|
| 10xxxx | 100000~109999 | 基础能力模块 |
| 20xxxx | 200000~209999 | 交付项目 |
| 30xxxx | 300000~309999 | |
| 40xxxx | 400000~409999 | |
| 10xxxx | 100000~109999 | |
| - | - | 预留50xxxx/60xxxx/70xxxx这三个区间段 |
| 80xxxx | 800000~809999 | 外部系统 |
| 90xxxx | 900000~909999 | 通用错误 |
- Swagger注解规范
- 使用Swagger V3注解为API提供文档，方便团队成员和其他开发者理解和使用接口。
【强制】在Controller类上添加@Tag注解，对每个接口方法添加@Operation注解，描述接口的作用。
【强制】使用@Parameter注解描述接口参数，使用@RequestBody注解描述请求体。
【强制】使用@ApiResponse注解描述响应。
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.media.Content;
import io.swagger.v3.oas.annotations.media.Schema;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.tags.Tag;
@RestController @RequestMapping("/api/user") @Tag(name = "用户管理", description = "用户相关操作接口")
public class UserController {
@Operation(summary = "获取用户信息", description = "根据用户ID获取用户信息")
@GetMapping("/{userId}")
public ResponseEntity<UserDTO> getUser(
@Parameter(description = "用户ID", required = true) @PathVariable Long userId) {
// 实现逻辑
}
@Operation(summary = "创建用户", description = "根据请求体中的用户信息创建新用户")
@PostMapping
public ResponseEntity<UserDTO> createUser(
@RequestBody(description = "用户信息", required = true, content = @Content(schema = @Schema(implementation = CreateUserRequest.class))) CreateUserRequest request) {
// 实现逻辑
}
@Operation(summary = "更新用户信息", description = "根据用户ID更新用户信息")
@PutMapping("/{userId}")
public ResponseEntity<UserDTO> updateUser(
@Parameter(description = "用户ID", required = true) @PathVariable Long userId,
@RequestBody(description = "用户信息", required = true, content = @Content(schema = @Schema(implementation = UpdateUserRequest.class))) UpdateUserRequest request) {
// 实现逻辑
}
@Operation(summary = "删除用户", description = "根据用户ID删除用户")
@DeleteMapping("/{userId}")
@ApiResponses(value = {
@ApiResponse(responseCode = "200", description = "成功", content = @Content(schema = @Schema(implementation = Void.class))),
@ApiResponse(responseCode = "404", description = "用户不存在", content = @Content(schema = @Schema(implementation = ErrorResponse.class)))
})
public ResponseEntity<Void> deleteUser(
@Parameter(description = "用户ID", required = true) @PathVariable Long userId) {
// 实现逻辑
}
}
