284 lines
No EOL
6.9 KiB
Markdown
284 lines
No EOL
6.9 KiB
Markdown
# 代码质量命令
|
||
|
||
## 目录
|
||
|
||
- [概述](#概述)
|
||
- [PHP 代码检查](#php-代码检查)
|
||
- [JavaScript 代码检查](#javascript-代码检查)
|
||
- [Markdown 代码检查](#markdown-代码检查)
|
||
- [重要的代码检查指南](#重要的代码检查指南)
|
||
- [示例工作流程](#示例工作流程)
|
||
- [理解代码检查输出](#理解代码检查输出)
|
||
- [提交前检查清单](#提交前检查清单)
|
||
- [与开发周期集成](#与开发周期集成)
|
||
- [其他代码检查工具](#其他代码检查工具)
|
||
- [故障排除](#故障排除)
|
||
- [备注](#备注)
|
||
|
||
## 概述
|
||
|
||
在对 WooCommerce 代码库进行更改时，请运行这些命令以确保代码质量并遵循编码标准。
|
||
|
||
有关详细的 PHP 代码检查样板和常见问题，请参阅 [php-linting-patterns.md](.ai/skills/woocommerce-dev-cycle/zh-cn/php-linting-patterns)。
|
||
|
||
有关 Markdown 代码检查规则和工作流程，请参阅 [markdown-linting.md](.ai/skills/woocommerce-dev-cycle/zh-cn/markdown-linting)。
|
||
|
||
## PHP 代码检查
|
||
|
||
### 检查 PHP 代码问题
|
||
|
||
```bash
|
||
pnpm run lint:changes:branch:php
|
||
```
|
||
|
||
检查已更改文件是否存在违反 WordPress 编码标准的问题（只读）。
|
||
|
||
### 修复 PHP 代码风格问题
|
||
|
||
```bash
|
||
# 自动修复 PHP 代码风格问题
|
||
pnpm run lint:php:fix
|
||
```
|
||
|
||
此命令：
|
||
|
||
- 自动修复可修复的代码风格违规问题
|
||
- 应用 WordPress 编码标准格式
|
||
- 直接修改文件
|
||
- 应在提交前运行
|
||
|
||
### 高级 PHP 代码检查
|
||
|
||
如果您需要更多控制，可以直接使用 phpcs 和 phpcbf：
|
||
|
||
```bash
|
||
# 检查特定文件或目录
|
||
vendor/bin/phpcs path/to/file.php
|
||
|
||
# 使用特定标准检查
|
||
vendor/bin/phpcs --standard=WordPress path/to/file.php
|
||
|
||
# 修复特定文件
|
||
vendor/bin/phpcbf path/to/file.php
|
||
|
||
# 显示所有违规（包括警告）
|
||
vendor/bin/phpcs -s path/to/file.php
|
||
```
|
||
|
||
## JavaScript 代码检查
|
||
|
||
### 检查 JS 代码问题
|
||
|
||
```bash
|
||
# 对分支中的更改运行 JS 代码检查
|
||
pnpm run lint:changes:branch:js
|
||
```
|
||
|
||
此命令：
|
||
|
||
- 仅检查当前分支中更改的 JavaScript/TypeScript 文件
|
||
- 识别代码风格和潜在问题
|
||
- 不修改文件
|
||
|
||
**重要：** 插件级别的 `.eslintignore` 排除了 `client/blocks/`，因此 `lint:changes:branch:js` 不会捕获区块代码中的 eslint 或 prettier 问题。对于区块更改，还需运行区块包的代码检查：
|
||
|
||
```bash
|
||
# 检查区块 JS/TS（通过 eslint 插件包含 prettier）
|
||
pnpm --filter=@woocommerce/block-library lint:js
|
||
|
||
# 自动修复区块 JS/TS 问题
|
||
pnpm --filter=@woocommerce/block-library lint:js-fix
|
||
```
|
||
|
||
有关详细的 JavaScript/TypeScript 代码检查配置和样板，请参阅 `client/admin/CLAUDE.md`。
|
||
|
||
## Markdown 代码检查
|
||
|
||
在更改后总是检查 Markdown 文件。完整详情请参阅 [markdown-linting.md](.ai/skills/woocommerce-dev-cycle/zh-cn/markdown-linting)。
|
||
|
||
**快速命令：**
|
||
|
||
```bash
|
||
# 自动修复大多数问题
|
||
markdownlint --fix path/to/file.md
|
||
|
||
# 检查剩余错误
|
||
markdownlint path/to/file.md
|
||
```
|
||
|
||
## 重要代码检查指南
|
||
|
||
### 仅修复您分支中的代码
|
||
|
||
**重要：** 仅修复您正在工作的分支中新增或修改的代码的代码检查错误。
|
||
|
||
除非特别要求，否则不要修复无关代码中的代码检查错误。
|
||
|
||
**为什么？**
|
||
|
||
- 保持拉取请求专注于实际更改
|
||
- 避免与其他分支发生合并冲突
|
||
- 使代码审查更容易
|
||
- 保持清晰的 Git 历史
|
||
|
||
### 示例工作流程
|
||
|
||
```bash
|
||
# 1. 进行您的代码更改
|
||
# ... 编辑文件 ...
|
||
|
||
# 2. 检查您所做的更改
|
||
git status
|
||
git diff
|
||
|
||
# 3. 对您的更改运行代码检查
|
||
pnpm run lint:changes:branch:php
|
||
|
||
# 4. 自动修复问题
|
||
pnpm run lint:php:fix
|
||
|
||
# 5. 查看修复内容
|
||
git diff
|
||
|
||
# 6. 如果需要，检查 JavaScript 更改
|
||
pnpm run lint:changes:branch:js
|
||
|
||
# 7. 提交您的更改
|
||
git add .
|
||
git commit -m "您的提交消息"
|
||
```
|
||
|
||
## 理解代码检查输出
|
||
|
||
### PHP CodeSniffer 输出
|
||
|
||
```text
|
||
文件: /path/to/file.php
|
||
----------------------------------------------------------------------
|
||
发现 2 个错误影响 2 行
|
||
----------------------------------------------------------------------
|
||
12 | 错误 | [x] 期望在左括号后有 1 个空格；
|
||
| | 但找到 0 个
|
||
25 | 错误 | [ ] 变量 "$orderID" 不是有效的蛇形命名法
|
||
| | 格式
|
||
----------------------------------------------------------------------
|
||
```
|
||
|
||
**图例说明:**
|
||
|
||
- `[x]` - 可通过 phpcbf/lint:php:fix 自动修复
|
||
- `[ ]` - 需要手动修复
|
||
|
||
### 常见 PHP 问题
|
||
|
||
1. **间距问题** - 通常可自动修复
|
||
|
||
```php
|
||
// 错误
|
||
if($condition){
|
||
|
||
// 正确
|
||
if ( $condition ) {
|
||
```
|
||
|
||
2. **命名约定** - 需要手动修复
|
||
|
||
```php
|
||
// 错误
|
||
$orderID
|
||
|
||
// 正确
|
||
$order_id
|
||
```
|
||
|
||
3. **Yoda 条件** - 需要手动修复
|
||
|
||
```php
|
||
// 错误
|
||
if ( $value === 'active' )
|
||
|
||
// 正确
|
||
if ( 'active' === $value )
|
||
```
|
||
|
||
## 提交前检查清单
|
||
|
||
在提交更改前：
|
||
|
||
- [ ] 运行 `pnpm run lint:changes:branch:php`
|
||
- [ ] 如果发现问题，运行 `pnpm run lint:php:fix`
|
||
- [ ] 如果修改了 JS 文件，运行 `pnpm run lint:changes:branch:js`
|
||
- [ ] 如果修改了区块 JS/TS 文件，运行 `pnpm --filter=@woocommerce/block-library lint:js-fix`
|
||
- [ ] 使用 `git diff` 查看所有自动修复
|
||
- [ ] 处理任何无法自动修复的剩余问题
|
||
- [ ] 运行测试以确保修复没有破坏功能
|
||
|
||
## 与开发周期集成
|
||
|
||
代码质量检查适应整体开发工作流程：
|
||
|
||
1. 进行代码更改
|
||
2. 运行相关测试（参见 running-tests.md）
|
||
3. **运行代码检查** ← 您在这里
|
||
4. **修复代码质量问题** ← 您在这里
|
||
5. 仅在测试通过且代码检查无误后提交更改
|
||
|
||
## 其他代码检查工具
|
||
|
||
### 运行其他 pnpm 脚本
|
||
|
||
WooCommerce 可能包含额外的代码检查脚本。检查可用脚本：
|
||
|
||
```bash
|
||
# 查看所有可用脚本
|
||
pnpm run
|
||
|
||
# 常见的额外脚本可能包括：
|
||
pnpm run lint # 检查所有文件
|
||
pnpm run lint:fix # 修复所有可自动修复的问题
|
||
pnpm run lint:php # 仅进行 PHP 检查
|
||
pnpm run lint:js # 仅进行 JavaScript 检查
|
||
```
|
||
|
||
## 故障排除
|
||
|
||
### Linting 命令未找到
|
||
|
||
**问题:** 命令失败，提示 "command not found"
|
||
|
||
**解决方案:** 安装依赖项：
|
||
|
||
```bash
|
||
pnpm install
|
||
```
|
||
|
||
### 报告问题过多
|
||
|
||
**问题：** 代码检查报告了您未更改的文件中的问题
|
||
|
||
**解决方案：** 请确保您使用的是针对特定分支的命令：
|
||
|
||
```bash
|
||
# 推荐 - 仅检查您的更改
|
||
pnpm run lint:changes:branch:php
|
||
|
||
# 避免 - 检查整个代码库
|
||
pnpm run lint:php
|
||
```
|
||
|
||
### 自动修复后的冲突
|
||
|
||
**问题:** 运行 lint:php:fix 后出现 Git 冲突
|
||
|
||
**解决方案:**
|
||
|
||
1. 检查自动修复的内容: `git diff`
|
||
2. 如果修复不正确，请还原: `git checkout -- path/to/file.php`
|
||
3. 手动处理这些问题
|
||
|
||
## 注意事项
|
||
|
||
- 代码质量工具帮助在整个代码库中保持一致性
|
||
- 自动修复节省时间，但应始终进行审查
|
||
- 某些问题需要手动干预和对上下文的理解
|
||
- 提交前必须进行代码检查，以确保符合代码质量标准 |
