226 lines
7.9 KiB
YAML
226 lines
7.9 KiB
YAML
# ┌─────────────────────────────────────────────────────────────────┐
|
||
# │ 电商订单管理系统 — 工程规范文档 │
|
||
# │ 团队：订单研发团队（后端6人 + 前端3人 + QA2人 + DevOps1人） │
|
||
# │ 最后更新：2026-07-15 │
|
||
# │ 仓库：[email protected]:order-team/oms.git │
|
||
# └─────────────────────────────────────────────────────────────────┘
|
||
#
|
||
# 项目背景：
|
||
# 面向 B 端商家的电商订单管理系统，日均订单量约 50 万单。
|
||
# 微服务架构：订单服务、支付服务、库存服务、物流服务。
|
||
# 技术栈：Java 17 + Spring Boot 3.2 + React 18 + TypeScript 5.3
|
||
#
|
||
# 架构说明：
|
||
# 订单服务采用 CQRS 模式，写操作走主库，读操作走从库。
|
||
# 消息队列使用 RocketMQ 5.x。
|
||
#
|
||
# 2026-07-15 会议纪要：
|
||
# - 讨论了 Node.js 事件循环阻塞问题
|
||
# - 决定在 async 函数中全面禁用 fs.readFileSync 等同步 API
|
||
# - 下个 Sprint 开始 Code Review 时执行
|
||
#
|
||
# 部署流程：
|
||
# 每周二、四发布，发布窗口 14:00-16:00。
|
||
# CI/CD Pipeline 详见 Jenkins 配置。
|
||
#
|
||
# 代码审查 Checklist：
|
||
# [ ] 安全规范是否遵守
|
||
# [ ] 命名规范是否一致
|
||
# [ ] 性能是否有明显瓶颈
|
||
# [ ] 代码风格是否统一
|
||
# [ ] 团队约定是否遵循
|
||
#
|
||
# ── 安全类 ──────────────────────────────────────────────────────────
|
||
#
|
||
# 反面示例（请勿模仿）：
|
||
#
|
||
# // Java: 硬编码密码
|
||
# public class DatabaseConfig {
|
||
# private String password = "Admin@123456";
|
||
# }
|
||
#
|
||
# // JavaScript: 使用 eval
|
||
# const data = eval(request.body);
|
||
#
|
||
# // JavaScript: innerHTML 赋值
|
||
# element.innerHTML = userInput;
|
||
#
|
||
# 正确做法：
|
||
#
|
||
# @Value("${db.password}")
|
||
# private String password;
|
||
#
|
||
# const data = JSON.parse(request.body);
|
||
#
|
||
# element.textContent = userInput;
|
||
#
|
||
|
||
- id: no-hardcoded-credentials
|
||
severity: error
|
||
description: 禁止在源码中硬编码密码、令牌、API Key 等敏感凭证
|
||
message: 检测到疑似硬编码凭证，请使用环境变量或密钥管理服务注入
|
||
languages: [javascript, typescript, java]
|
||
|
||
- id: no-eval-usage
|
||
severity: error
|
||
description: 禁止使用 eval() 函数，存在代码注入风险
|
||
message: eval() 存在安全风险，请使用 JSON.parse() 或 Function 构造器替代
|
||
languages: [javascript, typescript]
|
||
|
||
- id: no-innerhtml-assignment
|
||
severity: warning
|
||
description: 禁止直接赋值 innerHTML，可能导致 XSS
|
||
message: 避免直接操作 innerHTML，请使用 textContent 或 DOMPurify 清洗
|
||
|
||
# ── 命名规范类 ──────────────────────────────────────────────────────
|
||
#
|
||
# 参考规范：
|
||
# - Google Java Style Guide
|
||
# - Airbnb JavaScript Style Guide
|
||
#
|
||
# 反面示例：
|
||
#
|
||
# // 常量未使用大写
|
||
# static final int maxRetry = 3;
|
||
# static final String DbHost = "localhost";
|
||
#
|
||
# // 布尔变量无前缀
|
||
# let active = true;
|
||
# function check(): boolean { ... }
|
||
#
|
||
# 正确做法：
|
||
#
|
||
# static final int MAX_RETRY = 3;
|
||
# static final String DB_HOST = "localhost";
|
||
#
|
||
# let isActive = true;
|
||
# function canCheck(): boolean { ... }
|
||
#
|
||
|
||
- id: require-constant-case
|
||
severity: warning
|
||
description: 常量命名必须使用全大写加下划线（SCREAMING_SNAKE_CASE）
|
||
message: 常量应使用全大写命名，如 MAX_RETRY_COUNT
|
||
languages: [javascript, typescript, java]
|
||
|
||
- id: require-boolean-prefix
|
||
severity: info
|
||
description: 布尔变量和方法名应以 is/has/can/should 开头
|
||
message: 布尔变量建议添加 is/has/can/should 前缀以提升可读性
|
||
languages: [javascript, typescript]
|
||
|
||
# ── 性能类 ──────────────────────────────────────────────────────────
|
||
#
|
||
# 架构说明：
|
||
# 订单服务采用 CQRS 模式，写操作走主库，读操作走从库。
|
||
# 在高并发场景下，以下性能规范尤为重要。
|
||
#
|
||
# 反面示例：
|
||
#
|
||
# // O(n³) 的订单匹配逻辑
|
||
# for (const order of orders) {
|
||
# for (const item of order.items) {
|
||
# for (const warehouse of warehouses) {
|
||
# // 匹配逻辑...
|
||
# }
|
||
# }
|
||
# }
|
||
#
|
||
# 正确做法：
|
||
#
|
||
# const warehouseMap = new Map(warehouses.map(w => [w.id, w]));
|
||
# for (const order of orders) {
|
||
# for (const item of order.items) {
|
||
# const wh = warehouseMap.get(item.warehouseId);
|
||
# }
|
||
# }
|
||
#
|
||
|
||
- id: no-nested-loops-deep
|
||
severity: warning
|
||
description: 禁止三层及以上嵌套循环，时间复杂度过高
|
||
message: 检测到深层嵌套循环（≥3层），建议重构为扁平结构或使用查找表优化
|
||
languages: [javascript, typescript, java]
|
||
|
||
- id: no-sync-in-async
|
||
severity: warning
|
||
description: 异步函数内禁止调用同步阻塞 API
|
||
message: 在 async 函数中调用同步 API 会阻塞事件循环，请改用异步版本
|
||
languages: [javascript, typescript]
|
||
|
||
# ── 代码风格类 ──────────────────────────────────────────────────────
|
||
#
|
||
# 反面示例：
|
||
#
|
||
# // 无类型注解
|
||
# function createOrder(data) {
|
||
# return api.post('/orders', data);
|
||
# }
|
||
#
|
||
# // 魔法数字
|
||
# if (order.status === 3) { ... }
|
||
# setTimeout(retry, 5000);
|
||
#
|
||
# 正确做法：
|
||
#
|
||
# function createOrder(data: CreateOrderDTO): Promise<OrderResponse> {
|
||
# return api.post('/orders', data);
|
||
# }
|
||
#
|
||
# const ORDER_STATUS_SHIPPED = 3;
|
||
# const RETRY_DELAY_MS = 5000;
|
||
# if (order.status === ORDER_STATUS_SHIPPED) { ... }
|
||
# setTimeout(retry, RETRY_DELAY_MS);
|
||
#
|
||
|
||
- id: require-type-annotation
|
||
severity: info
|
||
description: 函数参数和返回值应显式标注 TypeScript 类型
|
||
message: 建议为函数添加显式类型注解，提升类型安全性
|
||
languages: [typescript]
|
||
|
||
- id: no-magic-numbers
|
||
severity: info
|
||
description: 禁止在代码中直接使用魔法数字，应提取为命名常量
|
||
message: 检测到魔法数字，建议提取为具名常量以提升可维护性
|
||
languages: [javascript, typescript]
|
||
|
||
# ── 团队约定类 ──────────────────────────────────────────────────────
|
||
#
|
||
# 部署流程说明：
|
||
# 每周二、四发布，发布窗口 14:00-16:00。
|
||
#
|
||
# 反面示例：
|
||
#
|
||
# throw new RuntimeException("失败");
|
||
# throw new Error("error");
|
||
#
|
||
# 正确做法：
|
||
#
|
||
# throw new OrderNotFoundException("订单不存在, orderId=" + orderId);
|
||
# throw new PaymentFailedException("支付失败", cause);
|
||
#
|
||
# 版本历史：
|
||
# v1.0 2026-06-01 张三 初版
|
||
# v1.1 2026-07-15 李四 新增性能规范
|
||
# v1.2 2026-08-01 王五 补充代码示例
|
||
#
|
||
|
||
- id: require-error-context
|
||
severity: warning
|
||
description: throw 语句必须携带错误上下文信息
|
||
message: throw 时应提供足够的上下文信息，便于问题定位
|
||
languages: [javascript, typescript, java]
|
||
|
||
- id: no-todo-in-production
|
||
severity: info
|
||
description: 生产代码中不应遗留 TODO/FIXME/HACK 注释
|
||
message: 代码中发现 TODO/FIXME/HACK 注释，请在发布前处理
|
||
excludeLanguages: [sql]
|
||
|
||
- id: require-function-doc
|
||
severity: info
|
||
description: 公共函数应添加文档注释（JSDoc / Javadoc）
|
||
message: 公共函数缺少文档注释，建议补充说明用途、参数和返回值
|
||
languages: [javascript, typescript, java]
|