Agent Skills
返回列表
高质量工程编码规范

高质量工程编码规范

开发编程 更新于 2026.08.29

将以下提示词粘贴到你的 AI 对话框中：

请根据 https://skillhub.cn/install/skillhub.md，安装 @user_a4c2f3d2/design-code。

技能介绍

你在解决什么问题

新接口不知道 Controller / Service / Repository 各写什么；一个 Service 方法涨到几百行；Code Review 时拿不准分层、事务、@Transactional 为何不生效；线上慢查询、N+1、异步里 TraceId 丢失；动态排序字段带来 SQL 注入风险；status == 1、吞异常、return null 列表这类坑反复出现。本技能把这些问题按场景索引到对应章节，而不是泛泛讲「写好代码」。

技能如何组织与落地

开篇用场景对照表直接跳转：分层职责、方法拆分、性能、日志、幂等、异步、SQL 安全、常量、设计模式、FAQ，以及订单状态流转完整案例。

核心内容按工程维度展开：

  • 架构：SOLID + 分层允许/禁止表（Handler 只做校验与编排，业务在 Service，数据在 Repository）
  • 质量与健壮性：方法 ≤50 行、卫语句、统一判空与入参校验、事务边界、异常分类、幂等（状态机 / 乐观锁 / 幂等键）
  • 运行态：N+1 与嵌套循环优化、日志级别与 log.error(msg, e)、统一线程池与上下文传递、动态 SQL 白名单
  • 对照清单：14 条典型错误与正确做法，适合 Review 逐项勾选

实战案例从「待支付→已完成」需求出发，串联枚举状态机、CAS 幂等、rollbackFor、异步通知与 VO/DTO 隔离，说明规范如何落在同一套代码里。

适用边界

这是多语言可映射的约定（文中给出 Java/MyBatis-Plus、JPA、C# EF、Go GORM、Python SQLAlchemy 等查询构造器对照），需结合你们项目已有的响应包装、工具库与命名风格统一执行。设计模式章节明确：简单 CRUD 不必套模式；只有一种实现时不要硬建工厂。严禁清单用于约束底线，不能替代你们团队的架构决策与领域建模。

使用场景

  • 新接口开发前，要按表划分 Controller 只做参数校验与编排、Service 承载业务与事务、Repository 只做数据访问，避免在 Handler 里写 SQL。
  • Code Review 时对照「典型错误清单」，逐项核对分层越界、空 catch、`return null` 列表、循环内 `selectById` 与动态排序未白名单等问题。
  • 支付、扣库存或审批类接口上线前，要用状态机校验、乐观锁或幂等键设计，避免多人重复提交导致同一条记录被覆盖。
  • 线上偶发失败却看不到堆栈时，按规范在关键节点打 info、在 catch 里用 `log.error("msg", id, e)` 并检查异步任务是否丢失 TraceId。

适合人员

  • 负责合并 PR 的后端工程师，需要可勾选的分层职责与 14 条典型错误对照项，减少评审时凭感觉挑刺。
  • 维护遗留代码的开发者，面对 300 行以上的 Service 方法，希望按「校验→查库→计算→写库」步骤拆成私有方法并保留可读主流程。
  • 承担接口 SLA 的工程师，要定位 N+1、嵌套循环和长事务导致的慢查询，并对照技能中的批量查询与 Map 关联模式改代码。
  • 实现订单或多状态审批流转的需求负责人，想参照「订单状态流转」案例落地枚举状态机、CAS 更新与异步通知的完整写法。