这里总结一下写接口的相关信息总结
我们先快速写好一个接口，5分钟，甚至更短
我们先想一个思路出来
一…确定好这个接口的骨架
1.先在纸上画出来，一共要创建几个类
2.每个类引入成员变量，以及几个方法要干啥
3.在核心关键层，service里的数据流转是什么
4.在对应mapper层，对应写的sql是什么
二.确定好的接口的标准
1.日志加了没，如果出问题，怎么添加日志最好
2.注释加了没，忘了这个接口的逻辑，如何1分钟理解get这个接口的数据流转
3.异常处理
4.特殊的需求，数据量考虑没，权限配置考虑没，响应时间考虑没
一、先用 5 分钟搭好骨架（不动手写代码）
1. 画清楚需要哪些类
Controller—— 接收请求、调用 Service、返回 VOService/ServiceImpl—— 核心业务逻辑Mapper/DAO—— 数据库访问Req / VO / DTO—— 入参、出参对象（按需）
2. 每个类的成员和方法（脑子里列一下即可）
| 类 | 关键成员 | 方法 |
|---|---|---|
| Controller | Service | postXxx()/getXxx() |
| Service | Mapper, 其他 Service | doXxx(param) |
| Mapper | - | selectByCondition()/insert()/update() |
3. Service 层的数据流转（核心）
请求 Req → 参数校验 → 业务判断（查库、计算）→ 执行持久化 → 组装 VO → 返回示例：
createUser→ 校验手机号是否重复 → 密码加密 →insert用户 → 返回UserVO（无密码）
4. Mapper 要写的 SQL 先想清楚
- 查：
SELECT ... WHERE ... ORDER BY ... LIMIT ... - 增：
INSERT INTO ... - 改：
UPDATE ... SET ... WHERE ... - 删：物理删除还是逻辑删除（
is_deleted = 1） - 复杂 SQL 放 XML，简单用注解；提前想好where 条件走索引。
二、合格接口的 4 个标准（写完必查）
1. 日志 —— 出问题不用猜
- 入口日志：打印核心请求参数（用
@Slf4j） - 关键分支日志：校验结果、第三方调用前后
- 异常日志：完整的
e对象，并带上业务标识 - 级别规范：
INFO正常流程，WARN可恢复异常，ERROR不可恢复错误
log.info("【createUser】开始, mobile={}",req.getMobile());log.error("【createUser】入库失败, mobile={}",req.getMobile(),e);2. 注释 —— 1 分钟捡起这个接口
- 类/方法用 Javadoc 写清：功能 + 主要步骤 + 入参/出参
- 复杂逻辑用行内注释解释“为什么这么写”
/** * 创建用户 * 1. 校验手机号唯一性 * 2. 密码加盐加密 * 3. 入库并返回用户信息（不含密码） */3. 异常处理 —— 别裸奔到前端
- Controller 层用全局异常处理器
@ControllerAdvice统一兜底 - Service 层抛出业务异常，携带错误码和提示信息
- 避免返回
entity或直接打印栈信息给调用方
4. 特殊需求必须考虑
- 数据量：是否需要分页？SQL 是否命中索引？是否可能慢查询？
- 权限：接口是否需要鉴权？数据是否按租户/用户隔离？
- 响应时间：是否有外部调用需要加超时、加缓存、异步处理？
- 并发：是否需要幂等（如支付回调）、是否加分布式锁？
三、5 分钟写完后的自检清单
- 入参校验加了（
@Valid+ 自定义校验） - 日志打在入口、异常、关键节点
- 注释能回答“做什么、步骤、入/出”
- 返回的是 VO 而不是裸 Entity
- 异常有统一处理，错误码明确
- SQL 条件字段有索引，防全表扫描
- 写操作加了事务
@Transactional - 敏感字段（密码、身份证）不落日志、不返回
总结成一句话：
画好流向定 SQL → 打好日志写注释 → 异常兜底想边界。
养成这个肌肉记忆，5 分钟出一个能交付、能交接的接口完全够用。
