15-spring-rest-api-conventions

Spring Boot REST API 编码约定

统一响应格式

所有 Controller 方法必须返回 R<T>，禁止直接返回裸对象或 ResponseEntity。

// ✅ 正确
@GetMapping("/{id}")
public R<UserVO> getUser(@PathVariable Long id) {
    return R.ok(userService.findById(id));
}

@DeleteMapping("/{id}")
public R<Void> deleteUser(@PathVariable Long id) {
    userService.delete(id);
    return R.ok();
}

// ❌ 禁止
@GetMapping("/{id}")
public UserVO getUser(@PathVariable Long id) { ... }

@GetMapping("/{id}")
public ResponseEntity<UserVO> getUser(@PathVariable Long id) { ... }

URL 路径规范

前缀	用途	鉴权要求
/api/admin/...	后台管理接口	@PreAuthorize("@authGuard.isSysUser(authentication)")
/api/app/...	前台用户接口	@PreAuthorize("@authGuard.isAppUser(authentication)") 或 @PublicApi

RESTful 风格：

• 列表：GET /api/admin/user/list 或 GET /api/admin/user/page
• 详情：GET /api/admin/user/{id}
• 新增：POST /api/admin/user
• 修改：PUT /api/admin/user/{id}
• 删除：DELETE /api/admin/user/{id}

依赖注入

统一使用构造器注入 + Lombok @RequiredArgsConstructor，禁止 @Autowired 字段注入。

// ✅ 正确
@RestController
@RequiredArgsConstructor
public class UserController {
    private final UserService userService;
    private final AuditLogService auditLogService;
}

// ❌ 禁止
@RestController
public class UserController {
    @Autowired
    private UserService userService;
}

权限与认证

后台接口

类级别添加 @PreAuthorize + @SecurityRequirement：

@SecurityRequirement(name = "Bearer")
@PreAuthorize("@authGuard.isSysUser(authentication)")
@RestController
@RequestMapping("/api/admin/xxx")
public class AdminXxxController { }

公开接口

无需登录的接口使用 @PublicApi 注解，SecurityConfig 自动放行：

@PublicApi
@GetMapping("/public/list")
public R<List<ItemVO>> publicList() { }

获取当前用户

使用 @AuthenticationPrincipal LoginUser 获取当前登录用户信息：

@PostMapping
public R<Void> create(@RequestBody @Valid CreateDTO dto,
                      @AuthenticationPrincipal LoginUser loginUser) {
    Long userId = loginUser.getUserId();
    // ...
}