PHP 项目 PR 提交规范指南
📋 目录
PR 提交规范
PR 标题格式
[类型] 简要描述（不超过50个字符）
示例：
[Feature] 添加用户登录功能
[Fix] 修复缓存过期问题
[Refactor] 重构数据库查询逻辑PR 类型说明
| 类型 | 说明 | 示例 |
|---|---|---|
| Feature | 新功能 | 添加支付接口 |
| Fix | 修复Bug | 修复空指针异常 |
| Refactor | 重构代码 | 优化代码结构 |
| Style | 格式修改 | 调整缩进、格式 |
| Test | 测试相关 | 添加单元测试 |
| Docs | 文档更新 | 更新API文档 |
| Perf | 性能优化 | 优化查询效率 |
| Chore | 构建/工具 | 更新依赖版本 |
PR 内容要求
必须包含：
## 变更原因
- 为什么要做这个变更
- 解决了什么问题
## 测试计划
- [ ] 单元测试
- [ ] 集成测试
- [ ] 手工测试
## 影响范围
- 影响哪些功能模块
- 是否需要数据库迁移Commit Message 规范
标准格式
<type>(<scope>): <subject>
<body>
<footer>实际示例
# 新功能 feat(auth): 添加用户登录功能 # 修复Bug fix(cache): 修复Redis缓存过期问题 # 重构 refactor(database): 重构ORM查询逻辑 # 性能优化 perf(query): 优化大表查询性能 # 文档 docs(api): 更新用户接口文档
Commit 类型规范
| Type | 用途 | 示例 |
|---|---|---|
| feat | 新功能 | feat: 添加订单导出 |
| fix | 修复 | fix: 修复登录报错 |
| docs | 文档 | docs: 更新README |
| style | 格式 | style: 调整代码格式 |
| refactor | 重构 | refactor: 重构验证逻辑 |
| test | 测试 | test: 添加测试用例 |
| chore | 构建 | chore: 更新依赖 |
代码规范
PSR 标准
PHP 项目必须遵循 PSR-12 编码规范
<?php
declare(strict_types=1);
namespace App\Services;
class UserService
{
public function createUser(string $name, string $email): User
{
// 使用强制类型声明
// 驼峰命名
// 4个空格缩进
}
}
命名规范
| 元素 | 规范 | 示例 |
|---|---|---|
| 类名 | 大驼峰 | UserController |
| 方法 | 小驼峰 | getUserInfo() |
| 变量 | 小驼峰 | $userName |
| 常量 | 全大写 | MAX_LIMIT |
| 函数 | 小驼峰 | get_user() ❌ → getUser() ✅ |
代码质量要求
// ✅ 遵循规范
class OrderService
{
/**
* 创建订单
*
* @param array $data 订单数据
* @return Order
* @throws \InvalidArgumentException
*/
public function createOrder(array $data): Order
{
// 1. 参数验证
if (empty($data['user_id'])) {
throw new \InvalidArgumentException('用户ID不能为空');
}
// 2. 业务逻辑
// 3. 返回结果
}
}
// ❌ 不遵循规范
class orderService
{
public function create_user($data)
{
// 没有类型声明
// 没有文档注释
// 命名不规范
}
}
测试要求
PHPUnit 测试示例
<?php
namespace Tests\Unit;
use PHPUnit\Framework\TestCase;
use App\Services\UserService;
class UserServiceTest extends TestCase
{
protected UserService $userService;
protected function setUp(): void
{
parent::setUp();
$this->userService = new UserService();
}
/** @test */
public function it_can_create_a_user()
{
$user = $this->userService->createUser('张三', 'test@example.com');
$this->assertInstanceOf(User::class, $user);
$this->assertEquals('张三', $user->getName());
$this->assertEquals('test@example.com', $user->getEmail());
}
}
覆盖率要求
- 新代码覆盖率 ≥ 80%
- 关键业务逻辑覆盖率 ≥ 90%
- 核心方法必须有测试
PR 模板
完整 PR 模板示例
## 描述 ### 变更内容 - 添加用户注册功能 - 实现邮箱验证 - 添加短信验证码 ### 为什么需要这个变更 - 支持新用户注册 - 提高账号安全性 ### 触发条件/相关Issue - Fixes #123 - Closes #456 ## 变更类型 - [x] 新功能 - [ ] Bug修复 - [ ] 代码重构 - [ ] 性能优化 - [ ] 文档更新 - [ ] 测试 ## 测试 ### 单元测试 - [x] UserRegistrationTest - [x] EmailVerificationTest ### 集成测试 - [x] 微信支付 - [ ] 支付宝支付 ### 手工测试步骤 1. 打开注册页面 2. 输入邮箱和密码 3. 点击注册按钮 4. 验证收到验证邮件 ## 检查清单 - [x] 代码遵循 PSR-12 规范 - [x] 所有测试通过 - [x] 无语法错误 - [x] 无未使用变量 - [x] 包含必要的注释 - [ ] 更新相关文档 - [x] 检查安全性（SQL注入、XSS等） ## 影响范围 - 影响模块：用户认证系统 - 是否需要数据库迁移：是 - 是否需要更新配置：否 ## 截图/演示 （如有必要，添加截图） ## 部署说明 - 需要执行 `composer install` - 需要更新环境变量
Git 操作规范
分支命名
feature/feature-name
fix/bug-name
refactor/refactor-name
docs/documentation-name
示例：
feature/user-login
fix/cache-expire-bug提交流程
# 1. 拉取最新的远程代码 git pull origin master # 2. 创建功能分支 git checkout -b feature/user-login # 3. 编写代码并提交 git add . git commit -m "feat: 添加用户登录功能" # 4. 推送分支 git push origin feature/user-login # 5. 创建PR（在GitHub/GitLab等平台）
常见问题处理
# 解决冲突 git merge master # 或 git rebase master # 修改提交信息 git commit --amend # 合并多个提交（squash） git rebase -i HEAD~3
代码检查清单
✅ 必查项
- [ ] 是否遵循 PSR-12 规范？
- [ ] 是否有严格的类型声明？
- [ ] 是否使用了 PHP 7.4+ 的语法特性？
- [ ] 是否有过长方法（建议 < 50行）？
- [ ] 是否有过度复杂的条件逻辑？
- [ ] 是否包含异常处理？
- [ ] 日志记录是否完善？
❌ 禁止项
- 禁止使用
var_dump、print_r调试代码 - 禁止使用全局变量
- 禁止使用单字母变量名（除循环变量）
- 禁止未使用的
use语句 - 禁止过长函数（超过100行）
- 禁止使用
eval等危险函数
自动化工具配置
PHP_CodeSniffer
# composer.json 中添加
"require-dev": {
"squizlabs/php_codesniffer": "^3.6",
"phpmd/phpmd": "^2.12"
}
Pre-commit 钩子
// .pre-commit-config.yaml
repos:
- repo: https://github.com/nunomaduro/phpinsights
rev: 2.0.2
hooks:
- id: phpinsights
💡 建议：团队内部应统一使用上述规范，并通过 CI/CD 工具自动检查代码质量，这不仅能提高代码质量,还能减少代码评审的工作量。
📌 重要：每次提交前，务必运行
composer test和composer lint确保代码质量。
