后端二次开发指南

面向后端开发者：如何新增接口、遵循权限与返回规范、使用缓存与事务。

1. 新增一个 Controller 方法

@XssCleanIgnore                          // 复杂 JSON 参数时标注，避免 XSS 误伤
@RequestMapping(value = "/myAction")
@ResponseBody
@LoginRequired(purview = "0")            // 权限：-1 公开 / 0 登录 / 2 超管
public String myAction(@RequestParam(value = "params", required = false) String params,
                       @RequestParam(value = "token", required = false) String token) {
    try {
        if (StringUtils.isBlank(params)) {
            return Result.getResultJson(0, "参数不能为空", null);
        }
        JSONObject json = JSONObject.parseObject(params);
        // 按需取用户
        Map map = redisHelp.getMapValue(this.dataprefix + "_" + "userInfo" + token, redisTemplate);
        Integer uid = Integer.parseInt(map.get("uid").toString());

        // ...业务逻辑，写库用对应 Service（xxxService.insert/update/selectByKey）

        return Result.getResultJson(1, "操作成功", null);
    } catch (Exception e) {
        logger.error("MyController接口异常", e);
        return Result.getResultJson(0, "接口请求异常", null);
    }
}

2. 权限注解速查

3. 参数与返回规范

• 列表类：入参 searchParams(JSON) + page/limit/searchKey/order；返回 {code,data,count,total}。
• 业务返回：{"code":1,"msg":"","data":...}；错误 {"code":0,"msg":"原因","data":null}。
• 对象字段：用实体接 JSON（jsonToMap.toJavaObject(TypechoXxx.class)）；注意前端传递字段名与实体一致。
• 金额：一律 BigDecimal，禁止 double/float 计算金额。
• 时间：项目使用 10 位秒级时间戳 String.valueOf(System.currentTimeMillis()).substring(0,10)。

4. 缓存规范

// 写缓存（秒）
redisHelp.setRedis(key, value, 30, redisTemplate);
// 读缓存
String cached = redisHelp.getRedis(key, redisTemplate);
// 列表缓存
redisHelp.setList(key, list, 30, redisTemplate);
redisHelp.getList(key, redisTemplate);
// 按模式删缓存
redisHelp.deleteKeysWithPattern("*" + this.dataprefix + "_xxx_*" + uid, redisTemplate, this.dataprefix);
// 删单个
redisHelp.delete(key, redisTemplate);

• 键命名：<dataprefix>_<业务>_<维度>（如 _soft_info_12_3）。
• 涉及用户态的缓存必须带 uid 隔离（如付费状态：_soft_info_{softId}_{uid}）。
• 更新数据后清相关缓存，否则出现脏读。

5. 事务使用

@Transactional(rollbackFor = Exception.class)
public String buy(...) {
    try {
        // 扣费、写流水、写记录
    } catch (Exception e) {
        logger.error("...", e);
        throw new RuntimeException("业务失败，事务回滚", e); // 必须 rethrow 才回滚
    }
}

6. 表结构变更流程

1. 修改实体 TypechoXxx.java 与对应 TypechoXxxMapper.xml（resultMap/列清单/insert/update 都要补列）。
2. 新建表→resources/xxx.sql（CREATE TABLE IF NOT EXISTS）；加列→InstallController 的幂等迁移段（查 information_schema.columns → ALTER ADD COLUMN）。
3. 管理端 RuleApiVisible「刷新数据表」触发 newInstall → proInstall 自动执行，老库自动补列。

7. 常见坑

• Mapper XML 是手写列清单：漏补列会导致 insert/update 丢字段（不报错但数据缺失）。
• 实体加字段但 XML 的 update 未加 <if>：该字段永远写不进去。
• searchParams 转实体后，XML where 未列出的字段不参与筛选（不报错，只是不筛）。