backend-common

name	backend-common
description	不自动触发, 由其他skill触发

Code Style

通用代码风格, 由其他skill触发

测试代码约定

• 如果用户要求生成测试方法，实现逻辑必须非常简单，方便直接运行和理解。
• 测试优先覆盖主流程、关键分支和明显边界，不写过度复杂的构造逻辑。

注释

• 每个方法必须有方法注释, 注释默认使用英文
• 注释直接说明业务目的和入参与返回关系，不写空泛表述。
• 生成注释时，优先解释“为什么这样处理”，不是重复代码字面意思。
• 关键代码必须加注释，重点解释业务判断、分支原因、边界处理和数据转换，不写无意义的逐行注释。
• 修改代码的同时, 一定要同步修改注释
• 实体与请求对象 各个字段要有字段说明, 用注释说明即可

sql

• 如涉及到表或字段操作, 请将 sql 保存到 file/sql 目录下, sql 文件命名为 {yyyy-mm-dd}.sql, 包括增量和存量
• 如果表已经存在, 请不要直接改动建表语句, 而是使用 'alter table' 命令
• 新增的表和字段, 需要加入注释
• 常用查询字段需要添加索引
• 新表必须包括以下字段

id        VARCHAR2(32) NOT NULL,
create_by VARCHAR2(32) DEFAULT '' NOT NULL,
create_at TIMESTAMP(6) DEFAULT CURRENT_TIMESTAMP NOT NULL,
update_by VARCHAR2(32),
update_at TIMESTAMP(6) DEFAULT CURRENT_TIMESTAMP,

• 禁止使用外键

方法

• 已有方法需要新增业务参数时，优先在当前真实调用点直接补齐参数，保持调用链最短。
• 多个代码块有复用代码的，抽离为工具类或私有方法，避免重复代码
• 没有复用的代码, 禁止单独抽成方法, 除非这个代码块有明显的业务含义同时行数超过了 50 行
• 尽量避免冗余设计, 优先选择直接实现，避免无实际价值的抽象和中间层; 没必要的包装方法, 自动删除, 换为使用入参
  • 比如如果两个方法(包括CRUD)的唯一区别只是传入不同的 true/false、常量、枚举或字符串，优先合并为一个真实方法，由调用方直接传参。
  • 禁止新增只有一层转发、没有独立业务语义的包装方法。
  • 禁止为了透传新增参数而连续新增一堆没有任何用途的重载方法。 没必要的包装方法, 自动删除, 换为使用入参
  • 禁止出现“旧方法只调用新方法并补 null/false/default 参数”的包装式重载。
  • 纯CRUD且没有超过两次的调用, 直接使用 mapper
• 字段匹配优先使用正则
• 禁止在代码里使用禁止使用自定义sql

变更边界

• 禁止修改与用户当前需求无关的代码、配置占位符、注释、格式、命名、依赖、接口 URL、调度表达式等内容。即使发现现有代码看起来不够优雅、不够一致、可能有更好的写法，也只能在回复中提示，不得顺手修改。
• 新增代码时优先做最小必要改动，不顺手扩展范围，不主动重构整条链路；除了用户要求的变更内容以外, 不顺手修问题，不整理其他代码的格式。
• 直接修改相关代码即可
• 能直接返回就直接返回，避免无意义的中间变量和多层嵌套
• 如果文件移动后, 之前的目录为空, 则删除之前的目录

配置项约束

• .gitignore 不存在, 自行生成
• 允许查看 Git 已知路径：已跟踪改动、已暂存新增、已暂存删除。
• 读取 .gitignore。禁止读取或提交以下内容：
  • */.mvn/*
  • */.idea/*
  • config/.env.*
  • .gitignore 中提到的内容
• 如果变更的代码中存在 todo，必须提醒用户(哪个文件：哪行代码)，并终止后续提交
• 代码里的相对路径是项目相对路径, 不是 agent 相对路径；
• 代码里用到的文件路径, 默认使用绝对路径字符串(直接从根目录写起, "/..." )

测试

• 默认无需你自动测试/验证功能，只用编译检查即可
• 如果用户明确要求测试,
  • 你不应该通过服务直接一开始就进行整体端测 而是一个个,每一个我需要你测试的地方, 自己完成单元测试用例, 逐个测试通过 需要联网的, 甚至需要你完成交叉测试验证用例 这种
  • 测试的相关类也要符合 ## 实体与请求对象 的约定
  • 不要使用 add_argument 之类的命令行参数解析方式包装测试入参，直接使用普通变量。
  • 测试优先覆盖主流程、关键分支和明显边界。除了 dify 等高星项目, 默认不要mock, 而是实际测试
    • 不使用 Mock客户端, 而是调用实际接口/执行实际业务
    • 不使用 Mock数据, 而是按接口业务, 传入实际文件/数据

核心规范

• 使用框架内已有的日志工具，在关键节点 加入 日志打印
• 缩进使用 tab； keep indents on empty lines
• 与本次修改无关的文件/代码/注释, 禁止删除
• 禁止使用 Map
• 根据用户要求, 基于项目代码, 直接修改代码或给出直接可用的代码修改意见, 禁止给出伪代码``大概是这样的代码等等
• 如需使用常量, 放到 constant 文件夹下合适的类中
• 先理解现有文件风格，再补全或修改代码。排版风格必须与当前项目整体一致, 必须逐行对照项目现有排版
• 输出默认到 file/output 目录下, 并加上时间戳
• 在满足 .gitignore 的前提下, 每次代码增删改，必须使用 git add .、git add -A自动添加生成后的代码文件