PHP项目团队协作规范

wen PHP项目 2026-08-11 211

PHP 项目团队协作规范

代码规范

1 PSR 标准遵循

必须遵循 PSR-1（基础编码规范）和 PSR-12（扩展编码规范）
推荐使用 PSR-4 自动加载标准
统一 PHP 版本（如 PHP 8.1+），禁止使用废弃函数

2 命名规范

类型	规范	示例
类名	大驼峰（StudlyCase）	`UserService`
方法名	小驼峰（camelCase）	`getUserList()`
变量名	小驼峰或蛇形	`$userName` / `$user_data`（选其一，团队统一）
常量	大写+下划线	`MAX_RETRY_COUNT`
数组键	蛇形（推荐）	`['user_name' => '张三']`
文件名	大驼峰（类文件）	`UserService.php`
数据库表	复数蛇形	`users`、`order_items`
数据库字段	蛇形	`created_at`

3 代码风格要求

缩进统一使用 4个空格（不使用 Tab）
单行代码不超过 120字符
每个 PHP 文件 必须以 <?php 开头，文件末尾 不保留闭合标签 ?>
类的大括号须另起一行（PSR-12），控制结构的大括号与关键字同行
不使用 echo 输出 HTML（应使用模板引擎）

<?php
declare(strict_types=1);
namespace App\Services;
use App\Repositories\UserRepository;
class UserService
{
    private UserRepository $repository;
    public function __construct(UserRepository $repository)
    {
        $this->repository = $repository;
    }
    public function getUserList(): array
    {
        $users = $this->repository->findAll();
        // 注释风格：解释"为什么"，而非"是什么"
        return array_map(function (array $user): array {
            return [
                'id' => (int) $user['id'],
                'user_name' => $user['user_name'],
            ];
        }, $users);
    }
}

版本控制（Git Flow）

1 分支模型

main        ├── 生产环境代码（受保护，不可直接推送）
hotfix/*    ├── 紧急修复（从 main 检出，修复后合并回 main 和 develop）
release/*   ├── 发布准备（从 develop 检出，合并回 main 和 develop）
develop     ├── 日常集成（受保护，不可直接推送）
feature/*   ├── 新功能开发（从 develop 检出，合并回 develop）
            └── 示例：feature/user-login

2 提交规范（Conventional Commits）

类型	说明	示例
feat	新功能	`feat: add user registration endpoint`
fix	修复 Bug	`fix: resolve null pointer exception in order module`
docs	文档变更	`docs: update README with API examples`
style	格式调整	`style: format code with php-cs-fixer`
refactor	代码重构	`refactor: extract payment logic to service class`
test	测试相关	`test: add unit tests for UserService`
chore	构建/工具	`chore: update composer dependencies`
perf	性能优化	`perf: add Redis cache for hot product queries`
revert	回滚提交	`revert: revert commit 2a3f4b5`

格式：
<type>(<scope>): <subject>
示例：
feat(order): add order cancellation API
- 新增订单取消接口
- 增加取消原因记录
- 补充单元测试
Refs: #123

3 Code Review 流程

所有代码合并到 develop 必须通过 Pull Request（或 Merge Request）
PR 至少 1-2 人 审查通过后方可合并
PR 需关联任务/缺陷编号
Review 重点：代码质量、逻辑正确性、安全漏洞、是否符合规范

环境与依赖管理

1 开发环境标准化

使用 Docker 统一开发环境（统一 PHP 版本、扩展、服务版本）
推荐使用 Laravel Sail 或 Docker Compose 搭建开发环境
PHP 版本、Composer 版本、扩展列表须在 README.md 中明确记录

2 Composer 依赖管理

所有依赖必须通过 composer.json 管理
生产依赖（require）与 开发依赖（require-dev）严格区分
提交 composer.lock 到 Git 仓库，确保生产安装一致
新增依赖须在 PR 中说明理由

测试规范

1 测试分层与覆盖目标

层级	技术要求	特点	覆盖目标
单元测试	PHPUnit	模拟外部依赖、不访问数据库	Service/Utility 类 ≥ 80%
集成测试	PHPUnit + TestCase	使用独立测试数据库	Repository/ORM 模型 ≥ 70%
接口测试	Pest 或 PHPUnit	模拟 HTTP 请求，使用独立测试数据库	Controller 核心接口 ≥ 90%
E2E 测试	Playwright（可选）	完整用户流程	核心业务链路 100%
静态分析	PHPStan / Psalm	不运行代码	严格级别 ≥ 6
代码风格	PHP-CS-Fixer	自动格式化	PSR-12 100%
安全审计	依赖漏洞扫描（如 `composer audit`）	检查依赖安全	零高危漏洞

2 测试命名和结构

目录结构：
tests/
├── Unit/          # 单元测试
│   └── Services/
│       └── UserServiceTest.php
├── Integration/   # 集成测试
│   └── Repositories/
│       └── UserRepositoryTest.php
└── Feature/       # 接口测试（Laravel 惯例）
    └── UserApiTest.php

命名约定： 测试方法用下划线或小驼峰描述行为,推荐形式：

PHP项目团队协作规范

// 推荐行为驱动风格
public function test_user_can_register_with_valid_data(): void
{
    // Arrange（准备数据）
    // Act（执行操作）
    // Assert（断言结果）
}

3 覆盖率要求

新代码行覆盖率 ≥ 80%
关键业务逻辑（支付、权限、数据处理）覆盖率 ≥ 90%
使用 phpunit --coverage-html ./coverage 生成报告

4 CI 自动化

每次 PR 必须通过 CI 全部检查（GitHub Actions / GitLab CI 均可）

# .github/workflows/ci.yml 示例
name: CI
on: [push, pull_request]
jobs:
  php-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: shivammathur/setup-php@v2
        with:
          php-version: '8.2'
          coverage: xdebug
      - run: composer install --prefer-dist --no-interaction
      - run: cp .env.ci .env
      - run: php artisan key:generate
      - run: vendor/bin/phpunit
      - run: vendor/bin/phpstan analyse --memory-limit=512M
      - run: vendor/bin/php-cs-fixer fix --dry-run --diff

数据库规范

1 迁移（Migration）

所有表结构变更必须通过迁移文件完成，禁止手动修改数据库
迁移文件名清晰描述用途：2024_01_15_100000_add_status_to_orders_table.php
每个迁移只做一件事
生产环境数据变更（数据修复、大批量更新）用独立数据迁移（如 Laravel 的 db:seed 或专门的数据迁移类）

2 索引设计

// 推荐使用迁移内建方法管理索引
Schema::table('orders', function (Blueprint $table) {
    $table->index('user_id');                    // 查询频繁字段
    $table->unique('order_no');                  // 业务唯一字段
    $table->index(['status', 'created_at']);     // 复合索引
});

索引设计三个"必须"：

所有外键必须建立索引
高频查询条件必须建立索引
复合索引必须遵守最左前缀原则

3 软删除与审计字段

核心业务表必须包含 created_at、updated_at 审计字段
需要保留历史数据的表使用 deleted_at 软删除（Laravel 的 SoftDeletes trait）
关键表可增加 created_by、updated_by 记录操作人

4 SQL 规范

禁止在循环中执行 SQL（N+1 问题），使用 eager loading（with()）
复杂查询使用查询构造器或 ORM，禁止拼接原生 SQL
大量数据操作用 chunk() 分批处理

安全规范

1 输入验证

所有用户输入必须经过验证
禁止直接拼接用户输入到 SQL 语句（使用预处理语句）
文件上传严格校验类型、大小、内容

2 输出转义

视图层输出使用模板引擎的自动转义（Blade 的）
禁止直接输出用户提交的 HTML 内容

3 认证与授权

使用框架内置认证机制（Laravel Sanctum / JWT）
接口必须实现权限控制（RBAC 或策略类）
敏感操作记录操作日志

4 敏感数据保护

密码使用 password_hash()，禁止明文或 MD5
.env 文件中的密钥严禁提交到 Git
API 密钥、数据库密码存于环境变量或密钥管理服务

日志与监控

1 日志规范

使用统一日志格式（JSON 结构化推荐）
日志级别使用规范：
- debug：调试信息（仅开发环境）
- info：常规操作记录
- notice：正常但重要事件
- warning：出现异常但未影响功能
- error：需要关注的错误
- critical：系统关键功能不可用
关键业务操作必须记录日志（订单创建、支付回调、用户注册等）

// 推荐方式
Log::channel('daily')->info('Order created', [
    'order_id' => $order->id,
    'user_id' => $order->user_id,
    'amount' => $order->amount,
]);

2 错误监控

部署 Sentry 或同类错误监控系统
生产环境关闭 display_errors，记录日志而非输出

文档规范

1 README 必需内容

项目简介与功能架构图
环境要求（PHP 版本、扩展、服务）
安装步骤（克隆、安装依赖、配置环境、初始化数据库）
常用命令（启动、测试、代码格式化）
目录结构说明
API 文档地址或说明

2 API 文档

使用 OpenAPI（Swagger） 或 Postman 维护 API 文档
接口变更必须同步更新文档
每个接口注明：请求方法、路径、参数、返回示例、错误码

3 代码内注释

复杂类、方法必须写 PHPDoc
注释说明意图而非机械重复代码
使用 @param、@return、@throws 标注

部署流程

1 发布流程

feature/* → develop（开发集成） → release/*（发布准备） → main（生产）
                    ↓                    ↓
              （自动测试）        （灰度验证/手动测试）

2 部署清单

[ ] 单元/集成测试全部通过
[ ] PHPStan/Psalm 静态分析通过
[ ] 代码风格检查通过
[ ] 依赖安全检查通过
[ ] 迁移文件已生成并测试
[ ] 环境变量配置已更新
[ ] 文档已同步更新
[ ] 版本号已更新（遵循语义化版本）

3 发布要求

每次发布必须打 Git Tag（如 v1.2.0）
紧急修复走 hotfix/* 分支，禁止直接在 main 修改
数据库迁移在生产环境执行前必须在预发布环境演练

沟通与协作流程

1 每日站会

每人汇报：昨日完成、今日计划、遇到的阻塞
时间控制在 15 分钟内

2 代码评审

提交 PR 时附上变更说明
评审人在 24 小时内完成评审
争议问题：在评审中解决，避免私下争论

3 任务管理

使用 Jira / 禅道 / Trello 等项目管理工具
任务状态：待处理 → 开发中 → 测试中 → 已完成
每个任务关联代码提交记录

十一、常用工具配置

1 PHP-CS-Fixer 配置（`.php-cs-fixer.php`）

<?php
return (new PhpCsFixer\Config())
    ->setRules([
        '@PSR-12' => true,
        'array_syntax' => ['syntax' => 'short'],
        'no_unused_imports' => true,
        'ordered_imports' => ['sort_algorithm' => 'alpha'],
        'single_quote' => true,
        'trailing_comma_in_multiline' => true,
    ])
    ->setFinder(
        PhpCsFixer\Finder::create()
            ->in(['app', 'routes', 'tests', 'database'])
    );

2 PHPStan 配置（`phpstan.neon`）

parameters:
    level: 6
    paths:
        - app
        - tests
    tmpDir: storage/framework/cache/phpstan

3 自动化 Githook

# .git/hooks/pre-commit（示例）
#!/bin/sh
if [ -f "vendor/bin/php-cs-fixer" ]; then
    vendor/bin/php-cs-fixer fix --dry-run --diff src/
    if [ $? -ne 0 ]; then
        echo "❌ 代码风格检查未通过，请先运行 php-cs-fixer fix"
        exit 1
    fi
fi
if [ -f "vendor/bin/phpstan" ]; then
    vendor/bin/phpstan analyse
    if [ $? -ne 0 ]; then
        echo "❌ 静态分析未通过"
        exit 1
    fi
fi
exit 0

十二、常见痛点与解决方案

常见问题	解决方案
每个人的代码风格不统一	强制使用 PHP-CS-Fixer + pre-commit 钩子
数据库结构混乱	所有变更走迁移，禁止手动修改
测试环境不一致	使用 Docker 统一环境
合并冲突频繁	小步提交（每次功能独立分支）、频繁合并 develop
安全漏洞被忽视	定期 `composer audit` + 依赖自动更新检查
代码走查流于形式	走查清单化（安全、性能、可读性、测试）

快速参考命令

# 安装依赖
composer install
# 运行测试
vendor/bin/phpunit
# 静态分析
vendor/bin/phpstan analyse
# 代码格式化
vendor/bin/php-cs-fixer fix
# 创建迁移
php artisan make:migration create_users_table
# 执行迁移
php artisan migrate
# 代码检查（一键组合）
composer check-all

规范可根据团队实际技术栈（Laravel / Symfony / ThinkPHP 等）和项目规模进行调整，核心原则是：自动化、一致性、可追溯、持续改进，建议在项目启动时与全体成员一起讨论确认,形成团队共识后严格执行。

本文地址： https://bmjup.com/post/43505.html