Skip to content

开发规范 ​

文件头注释 ​

每个新建文件必须在文件顶部添加标准注释块,包含功能描述、说明、作者信息。

后端文件(src/) ​

js
/**
 * 模块简要描述
 *
 * 详细功能说明(可选,复杂模块需要写清楚职责、业务场景、注意事项)
 *
 * @author yijiu2025
 * @since 2026-07-13
 */

迁移文件(migrations/) ​

js
/**
 * 迁移说明:本次迁移做什么(建表/加列/改数据/加密等)
 * 逆操作说明(down 是否能完全回滚、注意事项)
 *
 * @author yijiu2025
 * @since 2026-07-13
 */

完整示例 ​

后端工具类 (src/utils/crypto.js):

js
/**
 * 手机号加密工具
 * 使用 AES-256-CBC + 确定性 IV(HMAC-SHA256 派生),保证同一明文产生同一密文
 * 目的:加密存储手机号,同时保持唯一索引可用性
 *
 * @author yijiu2025
 * @since 2026-07-13
 */

迁移文件 (migrations/20260527000001-baseline-all-tables.js):

js
/**
 * 批量加密 user_user 表中现有的明文手机号
 * 加密后格式: base64(IV):base64(ciphertext)(含冒号分隔符)
 *
 * @author yijiu2025
 * @since 2026-07-13
 */

注释标签说明 ​

标签必填说明
@author✅作者标识(yijiu2025 / 开发者姓名)
@since✅创建日期(YYYY-MM-DD)
@param函数参数说明(类型 + 名称 + 用途)
@returns函数返回值说明
@example可选使用示例
@deprecated可选标记废弃 + 替代方案
@see可选关联模块引用

函数注释(JSDoc / TSDoc) ​

js
/**
 * 加密手机号
 * @param {string} plain - 明文手机号,如 '13812345678'
 * @returns {string} 加密字符串,格式: base64(IV):base64(ciphertext)
 */
function encryptPhone(plain) { ... }

export { encryptPhone };
ts
/**
 * 点赞/取消点赞(调后端 API + 乐观更新)
 * @param item - 作品对象
 * @throws 未登录时跳转登录页
 */
const handleLike = async (item: any) => { ... }

导出位置 ​

所有 export 一律收拢到文件末尾,定义处不写 export 关键字。完整约定(含违约示例与默认导出改法对照表)见 AGENTS.md 的「导出位置」一节,这里只给速查:

js
// ✅ 正确
function processOrder(order) { ... }
const MAX_RETRY = 3;

export { processOrder, MAX_RETRY };
export default orderService;
js
// ❌ 禁止
export function processOrder(order) { ... }
export const MAX_RETRY = 3;
export default new OrderService();

强制手段:

手段位置作用
ESLint no-restricted-syntaxeslint.config.js(files: src/**/*.js)拦截新写入的行内导出(编辑期即时报错)
契约测试src/__tests__/conventions/export-placement.test.js跨文件扫描全仓一致性(含 re-export 位置)

改写方式:这条规则没有 eslint --fix 自动修复(需要 AST 精确定位 + 保证导出面不变),小范围按上表手工改即可。


性能工程(后端) ​

后端性能要点见 best-practices/performance.md (缓存与 TTL、连接池、优雅关闭、慢请求告警、限流器往返次数)。三条铁律:

铁律一句话
先量后改没有实测数字(npm run bench 基线 / 火焰图 / EXPLAIN)就不动配置或索引
热路径不分配每请求都会走到的路径(守卫、IP 匹配、限流)禁止逐请求 new 对象 / 编译正则 / 查库
失效要主动缓存不是"设了 TTL 就安全" —— 权限变更必须主动失效,否则撤销会被推迟到过期

原先这里的「前端性能工程」整节已随前端工程一并迁出, 内容见 archive/legacy-frontend/frontend-performance-rules.md。

基于 GPL-3.0 许可发布