主题
接口规范
1. 路径
- 管理端统一前缀
/admin-api,模块名跟在后面:/admin-api/system/user/page。 - 资源使用复数名词,动作用子路径:
GET /page、POST /create、PUT /update、DELETE /delete、DELETE /delete-list、GET /get、GET /list。 - 门户/公开接口使用
@PermitAll并显式注释用途。
2. 入参与返回
json
// 成功
{ "code": 0, "msg": "", "data": { } }
// 分页
{ "code": 0, "msg": "", "data": { "list": [], "total": 0 } }
// 失败
{ "code": 1002000000, "msg": "用户不存在", "data": null }- 分页请求统一
pageNo、pageSize;排序SortingField(字段白名单校验)。 - 错误码 10 位:类型 + 系统 + 模块 + 序号;模块区间见
framework/pmforge-common/.../ServiceErrorCodeRange.java。 - 禁止返回裸实体;使用
*RespVO,敏感字段脱敏(@Desensitize)。
3. 鉴权
- 每个写接口必须有
@PreAuthorize("@ss.hasPermission('<module>:<entity>:<action>')")。 - 权限点必须存在于菜单 SQL(
system_menu.permission),新增权限点要同步 8 套数据库脚本。
4. 前端调用
web/pmforge-ui-web/src/lib/http.ts统一封装:注入Authorization与tenant-id,解包data,401 跳登录。- 新增页面前先用
docs/code/api/<module>.md或docs/.generated/code-index.json确认接口真实存在。