zhs123
43272d25eb
- 删除 7 个死模板文件 (products/services/quality/process/projects/customization/rfq) - 删除 13 个旧图片素材 (jpg/png/webp) - 新增 CDN SRI 完整性校验 (Bootstrap CSS/JS) - 新增面包屑导航模板组件 - 新增代码清理方案与代码审查标准文档 - 更新 README.md
267 lines
11 KiB
Markdown
267 lines
11 KiB
Markdown
# 代码审查标准与流程
|
||
|
||
> 适用项目：B2B Trade 主题（fragrance-trade）
|
||
> 技术栈：WordPress 经典主题 / PHP 7.4+ / Bootstrap 5.3 / jQuery
|
||
> 版本：v1.0 | 2026-07-24
|
||
|
||
---
|
||
|
||
## 一、审查原则
|
||
|
||
1. **安全优先** — WordPress 主题的 XSS / SQL 注入 / CSRF 是红线
|
||
2. **就事论事** — 评论针对代码，不针对人
|
||
3. **说清楚为什么** — 不只说"改这个"，要解释原因和潜在风险
|
||
4. **给方向不给答案** — 引导作者自己思考，除非是明确的安全漏洞
|
||
5. **赞美好代码** — 发现优秀实践要明确指出，让团队学习
|
||
|
||
---
|
||
|
||
## 二、优先级体系
|
||
|
||
每个审查意见必须标注以下级别之一：
|
||
|
||
| 级别 | 标记 | 含义 | 处理要求 |
|
||
|------|------|------|----------|
|
||
| 🔴 阻断 | Blocker | 安全漏洞 / 数据丢失 / 破坏功能 | **必须修复后才能合并** |
|
||
| 🟡 建议 | Suggestion | 输入验证缺失 / 性能问题 / 可维护性 | **应当修复，可协商** |
|
||
| 💭 细节 | Nit | 命名 / 风格 / 文档 | 修不修都行，不阻塞 |
|
||
|
||
---
|
||
|
||
## 三、WordPress 主题专项审查清单
|
||
|
||
### 🔴 阻断级检查项（必须全部通过）
|
||
|
||
#### 3.1 安全性
|
||
|
||
- [ ] **直接访问防护** — 所有 PHP 文件以 `if ( ! defined( 'ABSPATH' ) ) exit;` 开头
|
||
- [ ] **SQL 注入** — 禁止拼接 SQL；必须使用 `$wpdb->prepare()` 或 WP API（`get_posts()`, `WP_Query`）
|
||
- [ ] **XSS 防护** — 所有输出必须经过转义：
|
||
- HTML 文本 → `esc_html()`
|
||
- URL → `esc_url()`
|
||
- 属性 → `esc_attr()`
|
||
- 富文本 → `wp_kses_post()`
|
||
- [ ] **CSRF 防护** — 所有表单提交 / POST 处理必须有 `wp_nonce_field()` + `check_admin_referer()`
|
||
- [ ] **输入净化** — 所有 `$_POST` / `$_GET` / `$_SERVER` 必须用 `wp_unslash()` + 对应 `sanitize_*` 函数
|
||
- [ ] **邮件头注入** — 从用户输入构造邮件头时，必须剥离 `\r\n`
|
||
- [ ] **文件包含** — 禁止用户输入直接传入 `include` / `require` / `get_template_part()`
|
||
- [ ] **权限检查** — 任何管理员操作必须有 `current_user_can()` 检查
|
||
|
||
#### 3.2 功能正确性
|
||
|
||
- [ ] **关键路径错误处理** — 表单提交失败有 fallback（非空白白屏）
|
||
- [ ] **数据完整性** — 不会因空值 / 缺失字段导致 fatal error
|
||
- [ ] **重定向安全** — 使用 `wp_safe_redirect()` + `wp_validate_redirect()`，禁止直接 `header('Location:')`
|
||
|
||
### 🟡 建议级检查项
|
||
|
||
#### 3.3 输入验证与数据
|
||
|
||
- [ ] Customizer 字段是否有对应类型的 `sanitize_callback`
|
||
- [ ] `get_theme_mod()` 取值后是否有默认值兜底
|
||
- [ ] 用户上传的 URL 是否用 `esc_url_raw()` 存入、`esc_url()` 输出
|
||
|
||
#### 3.4 性能
|
||
|
||
- [ ] **N+1 查询** — 循环内不执行数据库查询，提前预取
|
||
- [ ] **资源加载** — 脚本用 `wp_enqueue_script`，不硬编码 `<script src>`
|
||
- [ ] **图片优化** — 使用响应式 `srcset` / `loading="lazy"`
|
||
- [ ] **Transient 缓存** — 耗时操作（远程请求、复杂查询）用 transient 缓存
|
||
|
||
#### 3.5 可维护性
|
||
|
||
- [ ] **死代码** — 新增模板文件必须有对应的 `get_template_part()` 调用；废弃文件及时删除
|
||
- [ ] **命名规范** — 函数 / 变量统一 `fragrance_trade_` 前缀，蛇形命名
|
||
- [ ] **函数长度** — 单函数不超过 80 行，超过则考虑拆分
|
||
- [ ] **重复代码** — 相同逻辑出现 3 次以上应提取为 helper 函数
|
||
- [ ] **文件组织** — 新功能按职责归入 `inc/` 对应模块，不堆在 `functions.php`
|
||
|
||
#### 3.6 前端质量
|
||
|
||
- [ ] **CDN 资源** — 第三方 CDN 必须有 SRI 完整性哈希 + 本地回退
|
||
- [ ] **第三方库** — 禁止将多个库的压缩代码拼接到单文件；用 npm + 构建流程管理
|
||
- [ ] **无障碍** — 图片有 `alt`，表单有 `label`，按钮有可读文本
|
||
- [ ] **响应式** — 移动端布局不溢出，触控目标不小于 44×44px
|
||
- [ ] `prefers-reduced-motion` — 动画尊重用户偏好
|
||
|
||
### 💭 细节级检查项
|
||
|
||
- [ ] 文本域统一为 `fragrance-trade`，所有字符串包裹 `__()` / `esc_html_e()`
|
||
- [ ] 注释说明"为什么"而非"做了什么"
|
||
- [ ] 长行拆分（单行 PHP echo 不超过 120 字符）
|
||
- [ ] CSS 自定义属性命名遵循 `--token-name` 格式
|
||
|
||
---
|
||
|
||
## 四、审查流程
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ 代码审查流程 │
|
||
├─────────────────────────────────────────────────────────────┤
|
||
│ │
|
||
│ 1. 提交前自检 │
|
||
│ 作者按 §三 清单自检 → 确认无 🔴 项 │
|
||
│ ↓ │
|
||
│ 2. 提交审查 │
|
||
│ Gitea PR / 提交说明 → 附上改动摘要和测试方式 │
|
||
│ ↓ │
|
||
│ 3. 审查者检查 │
|
||
│ 按 §三 清单逐项 → 标注 🔴🟡💭 → 写明原因和建议方向 │
|
||
│ ↓ │
|
||
│ 4. 分支处理 │
|
||
│ ├─ 有 🔴 → 打回，作者修复后重新提交 │
|
||
│ ├─ 有 🟡 → 讨论确认，修复或记录为后续任务 │
|
||
│ └─ 仅 💭 → 可选修复，直接通过 │
|
||
│ ↓ │
|
||
│ 5. 合并 │
|
||
│ 审查者 Approve → 作者合并 → 删除分支 │
|
||
│ ↓ │
|
||
│ 6. 回顾（每周） │
|
||
│ 汇总本周审查发现的共性问题 → 更新本标准 │
|
||
│ │
|
||
└─────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 4.1 提交规范
|
||
|
||
提交 PR / 提交审查时，标题格式：
|
||
|
||
```
|
||
[类型] 简述 — 具体改动
|
||
|
||
类型：feat / fix / refactor / style / security / docs / chore
|
||
```
|
||
|
||
示例：
|
||
```
|
||
[security] RFQ 表单 — 增加 nonce 验证
|
||
[feat] 案例详情页 — 添加施工前后对比图
|
||
[refactor] inc/defaults.php — 按区块分组重组配置键
|
||
```
|
||
|
||
### 4.2 审查时间线
|
||
|
||
| 阶段 | 时限 | 说明 |
|
||
|------|------|------|
|
||
| 初次审查 | 提交后 24h 内 | 审查者完成首轮检查 |
|
||
| 修复后复审 | 作者修复后 12h 内 | 审查者确认修复 |
|
||
| 超时升级 | 超 48h 未回应 | @项目负责人介入协调 |
|
||
|
||
---
|
||
|
||
## 五、审查评论模板
|
||
|
||
### 🔴 阻断级
|
||
|
||
```
|
||
🔴 [安全/XSS] 第 42 行：用户输入直接输出到 HTML
|
||
|
||
原因：
|
||
$subtitle 变量来自 $_POST，未经 esc_html() 转义直接 echo，
|
||
攻击者可注入 <script> 标签执行任意代码。
|
||
|
||
建议：
|
||
echo esc_html( $subtitle );
|
||
```
|
||
|
||
### 🟡 建议级
|
||
|
||
```
|
||
🟡 [性能/N+1] 第 18-25 行：循环内执行 get_post_meta()
|
||
|
||
原因：
|
||
在 while 循环内逐条查询 post_meta，10 篇文章 = 10 次查询，
|
||
页面加载时会明显变慢。
|
||
|
||
建议：
|
||
循环前用 get_post_meta( $post_ids, 'key', false ) 批量预取，
|
||
或在循环内缓存结果。
|
||
```
|
||
|
||
### 💭 细节级
|
||
|
||
```
|
||
💭 [命名] 第 8 行：$d 变量名过于简短
|
||
|
||
考虑改为 $display_date 或 $post_date，6 个月后回来看能秒懂。
|
||
```
|
||
|
||
---
|
||
|
||
## 六、当前项目待修复清单
|
||
|
||
基于 2026-07-24 代码扫描结果，以下问题应优先处理：
|
||
|
||
| 优先级 | 问题 | 文件 | 说明 |
|
||
|--------|------|------|------|
|
||
| 🟡 | 11 个死模板文件 | template-parts/home/ | products, services, quality, process, faq, rfq, factory, video, customization, documents, projects 未被引用 |
|
||
| 🟡 | plugins.js 拼接 6 个库 | assets/js/plugins.js | jQuery Easing + Jarallax + Colorbox + AOS + anime.js + HC-Sticky 混在一起，无版本标记，无法维护 |
|
||
| 🟡 | CDN 无 SRI | inc/setup.php:47-54 | Bootstrap + Google Fonts 缺少 integrity 哈希，无本地回退 |
|
||
| 🟡 | 零测试 | 全项目 | 无 phpunit / 无 .phpcs.xml / 无 CI |
|
||
| 💭 | defaults.php 扁平数组 | inc/defaults.php | ~170 个键未分组，可按区块拆分 |
|
||
| 💭 | jQuery 冗余依赖 | assets/js/theme.js | 仅 colorbox 用 jQuery，其余为原生 DOM，可考虑去掉 jQuery |
|
||
|
||
---
|
||
|
||
## 七、工具辅助
|
||
|
||
### 静态检查（建议引入）
|
||
|
||
```bash
|
||
# PHP 代码规范检查 — WordPress 标准
|
||
composer create-project wp-coding-standards/wpcs
|
||
phpcs --standard=WordPress --extensions=php inc/ template-parts/
|
||
|
||
# 自动修复可修复的问题
|
||
phpcbf --standard=WordPress --extensions=php inc/ template-parts/
|
||
```
|
||
|
||
### Git Pre-commit Hook（建议配置）
|
||
|
||
```bash
|
||
#!/bin/bash
|
||
# .git/hooks/pre-commit
|
||
# 提交前自动检查 PHP 语法 + 基本安全扫描
|
||
|
||
ERRORS=0
|
||
|
||
# 1. PHP 语法检查
|
||
for file in $(git diff --cached --name-only --diff-filter=ACM | grep "\.php$"); do
|
||
php -l "$file" > /dev/null 2>&1 || { echo "语法错误: $file"; ERRORS=1; }
|
||
done
|
||
|
||
# 2. 检查是否包含危险函数
|
||
for file in $(git diff --cached --name-only --diff-filter=ACM | grep "\.php$"); do
|
||
grep -n 'eval\s*(' "$file" && { echo "⚠️ eval() 检测到: $file"; ERRORS=1; }
|
||
grep -n 'exec\s*(' "$file" && { echo "⚠️ exec() 检测到: $file"; ERRORS=1; }
|
||
grep -n 'system\s*(' "$file" && { echo "⚠️ system() 检测到: $file"; ERRORS=1; }
|
||
done
|
||
|
||
exit $ERRORS
|
||
```
|
||
|
||
---
|
||
|
||
## 八、审查者轮值
|
||
|
||
| 角色 | 职责 |
|
||
|------|------|
|
||
| 主审 | 按 §三 清单逐项检查，出具审查意见 |
|
||
| 复审 | 对主审意见复核，确认无遗漏（可选） |
|
||
| 作者 | 回复意见，修复 🔴🟡 项，说明 💭 项处理决定 |
|
||
|
||
> 小团队（≤3人）可轮流担任主审，无需固定复审。
|
||
|
||
---
|
||
|
||
## 附录：本项目已有的优秀实践（请保持）
|
||
|
||
- ✅ 所有文件 `ABSPATH` 守卫
|
||
- ✅ RFQ 表单完整安全链：nonce + honeypot + 速率限制 + 邮件头注入防护
|
||
- ✅ Customizer 字段全部配置 `sanitize_callback`
|
||
- ✅ 统一 `fragrance_trade_` 函数前缀
|
||
- ✅ CSS 使用自定义属性设计令牌系统
|
||
- ✅ JS 尊重 `prefers-reduced-motion` + passive 事件监听
|
||
- ✅ `antispambot()` 邮件地址混淆
|