springboot-skills

name springboot-skills description Spring Boot 项目全套开发规范合集，涵盖 RESTful API 设计、编码规范、数据库设计、异常处理、日志监控、性能优化和安全开发。确保代码质量、一致性和可维护性。 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 项目