PHP PR 提交规范

PHP 项目 PR 提交规范指南

📋 目录

• PR 提交规范
• Commit Message 规范
• 代码规范
• 测试要求
• 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 确保代码质量。