aibot88 Spring Boot 项目开发规范合集
本合集包含 Spring Boot 项目的全套开发规范，共 7 个核心技能模块。这些规范是底线，不是建议——违反规则会导致严重的可维护性问题和性能隐患。
技能模块总览
| 技能名称 | 触发场景 | 核心内容 |
|---|---|---|
| springboot-api-standards | 编写 Controller、设计 API 接口、参数校验、分页接口、接口文档 | RESTful URL 设计、统一响应格式、Controller 规范、参数校验、分页策略、DTO/VO 规范 |
| springboot-coding-conventions | 编写 Java 代码、设计类结构、依赖注入、事务管理、Redis 使用 | 分层架构、命名规范、@Resource 注入、设计模式、Redis 规范、事务管理、Lombok 使用 |
| springboot-db-design | 创建表、编写 SQL、设计 schema、MyBatis Mapper、索引设计 | 表设计规范、Entity 规范、Mapper 规范、批量操作、数据库迁移 |
| springboot-exception-handling | 异常处理、错误码定义、自定义异常类、全局异常处理器 | 异常分类、错误码设计、全局异常处理器、Service 层异常策略、事务回滚 |
| springboot-logging-monitoring | 日志输出、日志级别配置、链路追踪、Metrics 埋点、异步日志 | 日志级别规范、结构化日志、日志脱敏、日志文件配置、链路追踪、监控指标 |
| springboot-performance | 数据库查询、列表接口、批量数据、缓存策略、高并发场景 | 禁止 N+1 查询、禁止 OFFSET 深分页、缓存防护、查询优化、连接池配置、异步处理 |
| springboot-security-standards | 认证鉴权、用户输入处理、SQL 查询、敏感数据、文件上传、CORS 配置 | SQL 注入防护、XSS 防护、密码安全、JWT/API Key 安全、敏感数据脱敏、输入校验 |
核心规范速查
1. 分层架构（必须遵守）
Controller（接口层）
↓ 调用
BizManageService（业务合并层）
↓ 调用一个或多个
Service（数据库业务层，基于 MyBatis Plus）
↓ 调用
Mapper/DAO（数据访问层）
↓ 操作
Database
关键规则：
- Controller 只接收参数、调用 BizManageService、返回响应，不写业务逻辑
- BizManageService 负责编排业务流程、组合多个 Service、事务管理
- Service 只做单表 CRUD，继承 MyBatis Plus
ServiceImpl - 依赖只能向下，不能反向或跳层
2. RESTful API 设计
GET /api/v1/users/list # 分页查询用户列表
GET /api/v1/users/detail?id=1 # 查询单个用户
POST /api/v1/users/save # 创建用户
POST /api/v1/users/update # 更新用户
DELETE /api/v1/users/1,2,3 # 删除用户（支持批量）
统一响应格式：
{
"code": 200,
"message": "操作成功",
"data": { ... },
"timestamp": 1711180800000
}
3. 依赖注入规范
统一使用 @Resource 注入（不用 @Autowired 和 @RequiredArgsConstructor）：
@Service
@Slf4j
public class OrderBizManageService {
@Resource
private OrderService orderService;
@Resource
private OrderItemService orderItemService;
}
4. 事务管理
@Transactional(rollbackFor = Exception.class)
public void createOrder(CreateOrderDTO dto) {
// 涉及多表写操作必须加事务
orderService.save(order);
orderItemService.saveBatch(items);
stockService.deduct(dto.getItems());
}
5. Redis 使用规范
Key 命名必须带系统前缀：
// 格式：{系统前缀}:{业务模块}:{类型}:{标识}
"systemCode:user:info:123"
"systemCode:group:config:gpt-4"
"systemCode:lock:order:ORD001"
所有缓存必须设置过期时间：
redisTemplate.opsForValue().set(key, value, 1, TimeUnit.HOURS);
6. 性能红线（绝对禁止）
禁止循环查库（N+1 问题）：
// ❌ 禁止
for (Order order : orders) {
User user = userMapper.selectById(order.getUserId());
}
// ✅ 正确：批量查询 + 内存关联
Set<Long> userIds = orders.stream().map(Order::getUserId).collect(Collectors.toSet());
Map<Long, User> userMap = userMapper.selectBatchIds(userIds).stream()
.collect(Collectors.toMap(User::getId, Function.identity()));
禁止 OFFSET 深分页：
// ❌ 禁止：深分页时性能极差
SELECT * FROM users LIMIT 10 OFFSET 100000;
// ✅ 正确：游标分页
SELECT * FROM users WHERE id > lastId ORDER BY id ASC LIMIT 10;
7. 异常处理
Service 层主动抛异常，全局异常处理器统一兜底：
// Service 层
if (user == null) {
throw new ResourceNotFoundException("用户", id);
}
// 全局异常处理器
@ExceptionHandler(ResourceNotFoundException.class)
public ResponseEntity<ApiResponse<Void>> handleResourceNotFound(ResourceNotFoundException ex) {
return ResponseEntity.status(HttpStatus.NOT_FOUND)
.body(ApiResponse.error(ex.getCode(), ex.getMessage()));
}
8. 日志级别规范
| 级别 | 场景 | 示例 |
|---|---|---|
| ERROR | 系统错误，需要立即关注 | 数据库连接失败、外部服务不可用 |
| WARN | 可预期的异常情况 | 用户认证失败、资源不存在 |
| INFO | 关键业务节点 | 服务启动、用户登录、订单创建 |
| DEBUG | 开发调试信息，生产环境关闭 | 方法入参出参、SQL 参数 |
9. SQL 注入防护
<!-- ✅ 安全：#{} 使用 PreparedStatement 预编译 -->
<select id="getUserByName" resultType="User">
SELECT * FROM users WHERE username = #{username}
</select>
<!-- ❌ 危险：${} 是字符串拼接 -->
<select id="getUserByName" resultType="User">
SELECT * FROM users WHERE username = '${username}'
</select>
10. 密码安全
// ✅ 正确：使用 BCrypt（自带盐值）
user.setPassword(passwordEncoder.encode(rawPassword));
// ❌ 禁止：明文存储、MD5、SHA-1
user.setPassword(rawPassword);
user.setPassword(DigestUtils.md5Hex(rawPassword));
代码检查清单
每次编写代码时逐条自检：
架构分层
- Controller 中是否写了业务逻辑？（应该只调用 BizManageService）
- 是否正确使用了 BizManageService 层？（涉及多表操作时）
- 依赖注入是否使用
@Resource？（不用@Autowired和@RequiredArgsConstructor）
API 设计
- URL 是否符合 RESTful 规范？（复数名词、动作路径统一）
- 是否返回统一的
ApiResponse<T>结构？ - 参数校验注解是否带
message？
数据库
- 表设计是否包含
created_at和updated_at？ - 是否每个字段都有 COMMENT？
- 是否避免了 N+1 查询？
- 分页是否避免了深分页（OFFSET）？
性能
- 是否在循环中调用了 Mapper/Service/Redis？（应改为批量查询）
- 缓存是否设置了过期时间？
- 是否考虑了缓存穿透/击穿/雪崩防护？
安全
- SQL 查询是否全部使用
#{}或 LambdaQueryWrapper？ - 用户输入是否经过校验？
- 密码是否使用 BCrypt 加密？
- 日志中是否打印了敏感信息？（密码、API Key、token）
异常与日志
- 业务异常是否继承
BusinessException？ - 事务是否加了
rollbackFor = Exception.class？ - 日志级别是否正确？（ERROR 记录堆栈、WARN 用于可预期异常）
各技能模块详细说明
完整规范请参考 references/ 目录下的详细文档。
| 技能模块 | 触发场景 | 核心内容 |
|---|---|---|
| api-standards | 编写 Controller、设计 API 接口、参数校验、分页接口 | URL 规范、统一响应格式、Controller 规范、DTO/VO 规范 |
| coding-conventions | 编写业务代码、依赖注入、事务管理、Redis 使用 | 分层架构、命名规范、@Resource 注入、事务管理、设计模式 |
| db-design | 创建表、编写 SQL、MyBatis Mapper、索引设计 | 表设计规范、Entity 规范、Mapper 规范、批量操作 |
| exception-handling | 异常处理、错误码定义、全局异常处理器 | 异常分类、错误码设计、全局异常处理器、Service 层策略 |
| logging-monitoring | 日志输出、链路追踪、Metrics 埋点、异步日志 | 日志级别、结构化日志、日志脱敏、链路追踪、监控指标 |
| performance | 数据库查询、列表接口、批量数据、缓存策略、高并发 | 禁止 N+1 查询、禁止深分页、缓存防护、查询优化、异步处理 |
| security-standards | 认证鉴权、用户输入、敏感数据、文件上传、CORS 配置 | SQL 注入防护、XSS 防护、密码安全、数据脱敏、输入校验 |
使用方式
本技能合集适用于以下开发场景：
| 开发场景 | 应用规范 |
|---|---|
| 编写 Controller 或 API 接口 | API 设计规范 |
| 编写业务逻辑代码 | 编码规范和分层架构 |
| 设计数据库表或编写 SQL | 数据库设计规范 |
| 处理异常或错误 | 异常处理规范 |
| 添加日志输出 | 日志规范 |
| 编写查询或列表接口 | 性能规范（检查 N+1、深分页等） |
| 处理用户输入或敏感数据 | 安全规范 |
文档结构
ai-coding-java-springboot-skills/
├─ skill.md # 本文件：技能合集总览
├─ README.md # 使用说明
├─ spec/ # 规范定义（待补充）
└─ references/ # 各技能详细文档
├─ springboot-api-standards.md
├─ springboot-coding-conventions.md
├─ springboot-db-design.md
├─ springboot-exception-handling.md
├─ springboot-logging-monitoring.md
├─ springboot-performance.md
└─ springboot-security-standards.md
版本: 1.0.0 适用范围: Spring Boot + MyBatis Plus + Redis 项目