API 设计规范

URL 约定

管理后台：/admin-api/{模块}/{实体}/{操作}
用户端：  /app-api/{模块}/{实体}/{操作}

• 实体名用 kebab-case（如 dict-type、order-item）
• 不使用复数形式

HTTP 方法映射

操作	方法	URL	说明
创建	POST	/create	@RequestBody
修改	PUT	/update	@RequestBody
删除	DELETE	/delete?id=1	@RequestParam
批量删除	DELETE	/delete-list?ids=1,2	@RequestParam
单条查询	GET	/get?id=1	@RequestParam
分页	GET	/page	Query String
列表	GET	/list / /list-all-simple	Query String
导出	GET	/export-excel	无 CommonResult

Controller 模板

@Tag(name = "管理后台 - {实体名}")
@RestController
@RequestMapping("/{模块}/{实体-kebab}")
@Validated
public class {Entity}Controller {

    @Resource
    private {Entity}Service {entity}Service;

    @PostMapping("/create")
    @Operation(summary = "创建{实体名}")
    @PreAuthorize("@ss.hasPermission('{模块}:{实体}:create')")
    public CommonResult<Long> create{Entity}(@Valid @RequestBody {Entity}SaveReqVO createReqVO) {
        return success({entity}Service.create{Entity}(createReqVO));
    }

    @PutMapping("/update")
    @Operation(summary = "修改{实体名}")
    @PreAuthorize("@ss.hasPermission('{模块}:{实体}:update')")
    public CommonResult<Boolean> update{Entity}(@Valid @RequestBody {Entity}SaveReqVO updateReqVO) {
        {entity}Service.update{Entity}(updateReqVO);
        return success(true);
    }

    @DeleteMapping("/delete")
    @Operation(summary = "删除{实体名}")
    @Parameter(name = "id", description = "编号", required = true, example = "1024")
    @PreAuthorize("@ss.hasPermission('{模块}:{实体}:delete')")
    public CommonResult<Boolean> delete{Entity}(@RequestParam("id") Long id) {
        {entity}Service.delete{Entity}(id);
        return success(true);
    }

    @GetMapping("/get")
    @Operation(summary = "获得{实体名}详情")
    @Parameter(name = "id", description = "编号", required = true, example = "1024")
    @PreAuthorize("@ss.hasPermission('{模块}:{实体}:query')")
    public CommonResult<{Entity}RespVO> get{Entity}(@RequestParam("id") Long id) {
        return success(BeanUtils.toBean({entity}Service.get{Entity}(id), {Entity}RespVO.class));
    }

    @GetMapping("/page")
    @Operation(summary = "获得{实体名}分页")
    @PreAuthorize("@ss.hasPermission('{模块}:{实体}:query')")
    public CommonResult<PageResult<{Entity}RespVO>> get{Entity}Page(@Valid {Entity}PageReqVO pageReqVO) {
        return success(BeanUtils.toBean({entity}Service.get{Entity}Page(pageReqVO), {Entity}RespVO.class));
    }
}

VO 设计

VO 类型	后缀	用途
分页请求	PageReqVO	继承 PageParam，分页查询入参
保存请求	SaveReqVO	创建+更新共用（id 更新时必传）
响应	RespVO	详情/列表/分页返回
精简响应	SimpleRespVO	下拉选项等轻量返回

VO 规则

• 创建和更新共用 SaveReqVO
• 必填字段用 @NotNull/@NotBlank + message
• 所有字段必须有 @Schema 注解
• 入参必须 @Valid 校验
• 禁止 Controller 直接接收 DO
• DO -> VO 用 BeanUtils.toBean()

响应格式

{ "code": 0, "msg": "", "data": { ... } }

分页：{ "code": 0, "data": { "total": 100, "list": [...] } }

Swagger 注解

• Controller: @Tag(name = "管理后台 - xxx")
• 方法: @Operation(summary = "xxx")
• 参数: @Parameter(name, description, required, example)
• VO 字段: @Schema(description, requiredMode, example)
• description 用中文，必填标注 REQUIRED，提供 example

错误码

// 格式：1-{模块编号}-{实体编号}-{序号}
ErrorCode {ENTITY}_NOT_EXISTS = new ErrorCode(1_0XX_0YY_000, "当前{实体}不存在");

权限码格式

{模块}:{实体}:{操作}（create/update/delete/query/export）