Skip to content

接口规范 ​

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 确认接口真实存在。