新增接口全流程（从零到上线）

用一个实际案例（软件库增加“收藏软件”接口）演示完整链路：后端 → 文档 → 前端 → 管理端。

第 1 步：后端实现

在 SoftController.java 增加方法（参考源码结构）：

@XssCleanIgnore
@RequestMapping(value = "/mark")
@ResponseBody
@LoginRequired(purview = "0")
public String mark(@RequestParam(value = "params", required = false) String params,
                   @RequestParam(value = "token", required = false) String token) {
    try {
        Map map = redisHelp.getMapValue(this.dataprefix + "_" + "userInfo" + token, redisTemplate);
        Integer uid = Integer.parseInt(map.get("uid").toString());
        JSONObject json = JSONObject.parseObject(params);
        Integer softId = json.getInteger("softId");
        // 幂等：已收藏直接成功
        // ...业务
        return Result.getResultJson(1, "操作成功", null);
    } catch (Exception e) {
        logger.error("SoftController接口异常", e);
        return Result.getResultJson(0, "接口请求异常", null);
    }
}

要求：@XssCleanIgnore（复杂参数）、@LoginRequired(purview="0")、返回统一 JSON。

第 2 步：编译并启动验证

cd RuleApiPro
mvn clean package -DskipTests
java -jar target/RuleApiPro.jar

用 Postman/接口工具验证：GET/POST /soft/mark 传 params={"softId":1} + token，期望 code=1。

第 3 步：更新接口文档

python docs/api/generate.py

脚本扫描 Controller 源码自动生成对应 md（新接口自动出现）。若为复杂返回，建议在 md 中手工补充响应示例。

第 4 步：前端封装与页面

RuleAppRro/utils/api.js：

softMark: function () {
  return API_URL + 'soft/mark';
},

页面调用：

that.$Net.request({
  url: that.$API.softMark(),
  data: { params: JSON.stringify({ softId: 1 }), token: that.token },
  method: "get",
  success: function (res) {
    if (res.data.code == 1) uni.showToast({ title: "已收藏", icon: 'none' });
  }
});

同步到 RuleAppX（注意 Vue3 差异）。

第 5 步：管理端/权限复核

• 如需后台管理：在 RuleApiVisible 对应页面加入口调用后端管理接口。
• 权限越权自查：公开接口注意 isLogin 全局开关；管理接口确认 purview 级别。

第 6 步：回归与文档站

• 全链路回归：登录态/未登录态、超参/缺参、重复调用幂等。
• 同步 docs/api 重新生成；若涉及表结构，按《02》第 6 节补 sql + InstallController 迁移，管理端“刷新数据表”。

检查清单

• [ ] 后端返回 code=1/0 + msg
• [ ] 权限注解正确
• [ ] params JSON 解析 + 字段校验
• [ ] Mapper XML 列清单补齐（涉及表）
• [ ] 表变更同步 InstallController
• [ ] generate.py 重新生成文档
• [ ] api.js 封装 + 页面调用 + X 镜像同步
• [ ] 幂等/防刷/限频考虑