JavaAPI接口规范

2023-11-27 本文已影响0人那些年搬过的砖

接口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) {
    // 实现逻辑
}


}

JavaAPI接口规范

猜你喜欢

热点阅读