285 lines
7.6 KiB
Markdown
285 lines
7.6 KiB
Markdown
# 电商订单管理系统 — 工程规范文档
|
||
|
||
> 本文档由订单研发团队维护，最后更新于 2026 年 7 月。
|
||
|
||
## 项目背景
|
||
|
||
本项目是一个面向 B 端商家的电商订单管理系统，日均订单量约 50 万单。系统采用微服务架构，包含订单服务、支付服务、库存服务和物流服务四个核心模块。
|
||
|
||
技术栈：
|
||
- 后端：Java 17 + Spring Boot 3.2 + MyBatis-Plus
|
||
- 前端：React 18 + TypeScript 5.3 + Vite
|
||
- 数据库：MySQL 8.0 + Redis 7
|
||
- 消息队列：RocketMQ 5.x
|
||
|
||
## 团队介绍
|
||
|
||
订单研发团队目前有 12 人：
|
||
- 后端 6 人（含 1 名 Tech Lead）
|
||
- 前端 3 人
|
||
- QA 2 人
|
||
- DevOps 1 人
|
||
|
||
团队代码仓库：`[email protected]:order-team/oms.git`
|
||
|
||
## 一、安全相关规范
|
||
|
||
在 2026 Q2 的安全审计中，我们发现线上代码中存在硬编码的数据库密码，导致一次严重的安全事件。因此制定以下规范：
|
||
|
||
### 1.1 禁止硬编码凭证
|
||
|
||
severity: error
|
||
适用语言：JavaScript、TypeScript、Java
|
||
|
||
禁止在源码中硬编码密码、令牌、API Key 等敏感凭证。检测到疑似硬编码凭证时，请使用环境变量或密钥管理服务注入。
|
||
|
||
以下是一个**反面示例**（请勿模仿）：
|
||
|
||
```java
|
||
// ❌ 错误做法
|
||
public class DatabaseConfig {
|
||
private String password = "Admin@123456";
|
||
private String apiKey = "sk-abc123xyz";
|
||
}
|
||
|
||
// ✅ 正确做法
|
||
public class DatabaseConfig {
|
||
@Value("${db.password}")
|
||
private String password;
|
||
|
||
@Value("${api.key}")
|
||
private String apiKey;
|
||
}
|
||
```
|
||
|
||
### 1.2 禁止使用 eval()
|
||
|
||
severity: error
|
||
适用语言：JavaScript、TypeScript
|
||
|
||
上周代码审查中发现前端模块有 `eval()` 调用，存在代码注入风险。eval() 存在安全风险，请使用 JSON.parse() 或 Function 构造器替代。
|
||
|
||
```javascript
|
||
// ❌ 错误：使用 eval 解析用户输入
|
||
const data = eval(request.body);
|
||
|
||
// ✅ 正确：使用 JSON.parse
|
||
const data = JSON.parse(request.body);
|
||
```
|
||
|
||
### 1.3 禁止直接赋值 innerHTML
|
||
|
||
severity: warning
|
||
|
||
这是一条通用规则，适用于所有语言（因为各端都可能涉及 DOM 操作）。避免直接操作 innerHTML，请使用 textContent 或 DOMPurify 清洗。
|
||
|
||
相关讨论参见 [内部 Wiki: XSS 防护指南](https://wiki.internal/security/xss)
|
||
|
||
## 二、命名规范
|
||
|
||
> 以下命名规范参考了 Google Java Style Guide 和 Airbnb JavaScript Style Guide，根据团队实际情况做了调整。
|
||
|
||
### 2.1 常量命名
|
||
|
||
severity: warning
|
||
适用语言：JavaScript、TypeScript、Java
|
||
|
||
常量命名必须使用全大写加下划线（SCREAMING_SNAKE_CASE）。常量应使用全大写命名，如 MAX_RETRY_COUNT。
|
||
|
||
```java
|
||
// ❌ 错误
|
||
static final int maxRetry = 3;
|
||
static final String DbHost = "localhost";
|
||
|
||
// ✅ 正确
|
||
static final int MAX_RETRY = 3;
|
||
static final String DB_HOST = "localhost";
|
||
```
|
||
|
||
### 2.2 布尔变量前缀
|
||
|
||
severity: info
|
||
适用语言：JavaScript、TypeScript
|
||
|
||
布尔变量和方法名应以 is/has/can/should 开头。布尔变量建议添加 is/has/can/should 前缀以提升可读性。
|
||
|
||
```typescript
|
||
// ❌ 错误
|
||
let active = true;
|
||
let user = { verified: true };
|
||
function check(): boolean { ... }
|
||
|
||
// ✅ 正确
|
||
let isActive = true;
|
||
let user = { isVerified: true };
|
||
function canCheck(): boolean { ... }
|
||
```
|
||
|
||
## 三、性能规范
|
||
|
||
### 架构说明
|
||
|
||
订单服务采用 CQRS 模式，写操作走主库，读操作走从库。在高并发场景下，以下性能规范尤为重要。
|
||
|
||
### 3.1 禁止深层嵌套循环
|
||
|
||
severity: warning
|
||
适用语言：JavaScript、TypeScript、Java
|
||
|
||
禁止三层及以上嵌套循环，时间复杂度过高。检测到深层嵌套循环（≥3层）时，建议重构为扁平结构或使用查找表优化。
|
||
|
||
```javascript
|
||
// ❌ 错误：O(n³) 的订单匹配逻辑
|
||
for (const order of orders) {
|
||
for (const item of order.items) {
|
||
for (const warehouse of warehouses) {
|
||
// 匹配逻辑...
|
||
}
|
||
}
|
||
}
|
||
|
||
// ✅ 正确：使用 Map 优化为 O(n)
|
||
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);
|
||
}
|
||
}
|
||
```
|
||
|
||
### 3.2 异步函数内禁止同步 API
|
||
|
||
severity: warning
|
||
适用语言：JavaScript、TypeScript
|
||
|
||
异步函数内禁止调用同步阻塞 API。在 async 函数中调用同步 API 会阻塞事件循环，请改用异步版本。
|
||
|
||
### 2026-07-15 会议纪要
|
||
|
||
- 讨论了 Node.js 事件循环阻塞问题
|
||
- 决定在 async 函数中全面禁用 fs.readFileSync 等同步 API
|
||
- 下个 Sprint 开始 Code Review 时执行
|
||
|
||
## 四、代码风格
|
||
|
||
### 4.1 函数显式类型注解
|
||
|
||
severity: info
|
||
适用语言：TypeScript
|
||
|
||
函数参数和返回值应显式标注 TypeScript 类型。建议为函数添加显式类型注解，提升类型安全性。
|
||
|
||
```typescript
|
||
// ❌ 错误
|
||
function createOrder(data) {
|
||
return api.post('/orders', data);
|
||
}
|
||
|
||
// ✅ 正确
|
||
function createOrder(data: CreateOrderDTO): Promise<OrderResponse> {
|
||
return api.post('/orders', data);
|
||
}
|
||
```
|
||
|
||
### 4.2 禁止魔法数字
|
||
|
||
severity: info
|
||
适用语言：JavaScript、TypeScript
|
||
|
||
禁止在代码中直接使用魔法数字，应提取为命名常量。检测到魔法数字，建议提取为具名常量以提升可维护性。
|
||
|
||
```javascript
|
||
// ❌ 错误
|
||
if (order.status === 3) { ... }
|
||
setTimeout(retry, 5000);
|
||
|
||
// ✅ 正确
|
||
const ORDER_STATUS_SHIPPED = 3;
|
||
const RETRY_DELAY_MS = 5000;
|
||
if (order.status === ORDER_STATUS_SHIPPED) { ... }
|
||
setTimeout(retry, RETRY_DELAY_MS);
|
||
```
|
||
|
||
## 五、团队约定
|
||
|
||
### 部署流程说明
|
||
|
||
部署流程参考 CI/CD Pipeline 文档。每周二、四发布，发布窗口为 14:00-16:00。
|
||
|
||
### 5.1 throw 语句携带上下文
|
||
|
||
severity: warning
|
||
适用语言：JavaScript、TypeScript、Java
|
||
|
||
throw 语句必须携带错误上下文信息。throw 时应提供足够的上下文信息，便于问题定位。
|
||
|
||
```java
|
||
// ❌ 错误
|
||
throw new RuntimeException("失败");
|
||
throw new Error("error");
|
||
|
||
// ✅ 正确
|
||
throw new OrderNotFoundException("订单不存在, orderId=" + orderId);
|
||
throw new PaymentFailedException("支付失败", cause);
|
||
```
|
||
|
||
### 5.2 禁止遗留 TODO 注释
|
||
|
||
severity: info
|
||
排除语言：SQL
|
||
|
||
生产代码中不应遗留 TODO/FIXME/HACK 注释。代码中发现 TODO/FIXME/HACK 注释，请在发布前处理。
|
||
|
||
> 注：SQL 脚本中允许临时性的 TODO 标记，因为数据库迁移脚本的生命周期与代码不同。
|
||
|
||
### 5.3 公共函数文档注释
|
||
|
||
severity: info
|
||
适用语言：JavaScript、TypeScript、Java
|
||
|
||
公共函数应添加文档注释（JSDoc / Javadoc）。公共函数缺少文档注释，建议补充说明用途、参数和返回值。
|
||
|
||
```java
|
||
/**
|
||
* 创建订单
|
||
* @param request 订单创建请求
|
||
* @return 订单创建结果
|
||
* @throws InsufficientStockException 库存不足时抛出
|
||
*/
|
||
public OrderResult createOrder(CreateOrderRequest request) { ... }
|
||
```
|
||
|
||
```typescript
|
||
/**
|
||
* 获取用户订单列表
|
||
* @param userId 用户ID
|
||
* @param page 分页参数
|
||
* @returns 订单列表
|
||
*/
|
||
function getUserOrders(userId: string, page: Pagination): Promise<Order[]> { ... }
|
||
```
|
||
|
||
## 附录
|
||
|
||
### A. 代码审查 Checklist
|
||
|
||
- [ ] 安全规范是否遵守
|
||
- [ ] 命名规范是否一致
|
||
- [ ] 性能是否有明显瓶颈
|
||
- [ ] 代码风格是否统一
|
||
- [ ] 团队约定是否遵循
|
||
|
||
### B. 相关链接
|
||
|
||
- [Google Java Style Guide](https://google.github.io/styleguide/javaguide.html)
|
||
- [Airbnb JavaScript Style Guide](https://github.com/airbnb/javascript)
|
||
- [TypeScript ESLint Rules](https://typescript-eslint.io/rules/)
|
||
|
||
### C. 版本历史
|
||
|
||
| 版本 | 日期 | 作者 | 变更说明 |
|
||
|------|------|------|----------|
|
||
| 1.0 | 2026-06-01 | 张三 | 初版 |
|
||
| 1.1 | 2026-07-15 | 李四 | 新增性能规范 |
|
||
| 1.2 | 2026-08-01 | 王五 | 补充代码示例 |
|