PHP 团队代码规范制定

我来帮你制定一份完整的PHP团队代码规范,这份规范会涵盖从基础编码风格到高级实践的所有关键点。

PHP团队代码规范

编码风格基础

1 PSR标准遵循

// 强制遵循PSR-12扩展编码风格
- PSR-1: 基础编码标准
- PSR-4: 自动加载规范
- PSR-12: 扩展编码风格

2 缩进与空格

// 使用4个空格进行缩进（不使用Tab）
if ($condition) {
    // 4个空格缩进
    $result = someFunction();
}
// 运算符两侧添加空格
$total = $price * $quantity;
$isValid = ($status === 'active') && ($type === 'paid');
// 控制结构关键词后添加空格
if ($condition) {}
while ($condition) {}
for ($i = 0; $i < 10; $i++) {}
foreach ($items as $item) {}

命名规范

1 变量命名

// 使用驼峰式命名（camelCase）
$userName = 'John';
$isActive = true;
$totalAmount = 100.50;
// 私有属性使用下划线前缀（可选）
private $_internalId;
// 避免使用拼音/缩写
// 错误: $yhbh = '用户编号';
// 正确: $userCode = 'U001';

2 常量定义

// 使用大写字母和下划线
const MAX_RETRY_COUNT = 3;
define('APP_VERSION', '1.0.0');
// 类常量
class DatabaseConfig {
    public const HOST = 'localhost';
    private const PASSWORD = 'secret';
}

3 函数与方法

// 使用驼峰式命名
function getUserById($id) { }
function calculateTotalAmount($items) { }
// 私有方法使用下划线前缀（可选）
private function _formatResponse($data) { }

4 类名

// 使用帕斯卡命名（PascalCase）
class UserAccount {}
class DatabaseConnection {}
abstract class BaseModel {}
interface CacheInterface {}
trait LoggerTrait {}

注释规范

1 文件头注释

<?php
/**
 * UserService.php
 * 
 * 用户服务类，处理用户相关业务逻辑
 *
 * @author    团队名称
 * @copyright Copyright (c) 2024
 * @license   MIT License
 * @link      https://example.com
 * @package   App\Services
 */

2 方法注释

/**
 * 根据用户ID获取用户信息
 *
 * @param int $id 用户ID
 * @param bool $withDetails 是否包含详细信息
 *
 * @return array|null 返回用户数据数组，不存在时返回null
 *
 * @throws \InvalidArgumentException 当ID小于0时抛出异常
 */
public function getUserById($id, $withDetails = false)
{
    if ($id < 0) {
        throw new \InvalidArgumentException('User ID cannot be negative');
    }
    // 方法实现
}

3 复杂逻辑注释

// 使用SQL的LEFT JOIN来避免N+1查询问题
// 先获取所有订单，再批量获取用户信息
$orders = $this->getOrders();
$userIds = array_unique(array_column($orders, 'user_id'));
$users = $this->getUsersByIds($userIds);

代码组织结构

1 目录结构

project/
├── app/
│   ├── Controllers/       # 控制器
│   ├── Models/            # 模型
│   ├── Services/          # 服务层（业务逻辑）
│   ├── Repositories/      # 数据访问层
│   ├── Middleware/        # 中间件
│   └── Exceptions/        # 自定义异常
├── config/                # 配置文件
├── database/              # 迁移文件和种子数据
├── routes/                # 路由配置
├── public/                # 公共资源
├── resources/             # 视图和资源文件
└── tests/                 # 测试文件

2 单一职责原则

// 每个类只负责一项职责
class UserService {
    public function register($data) { }
    public function login($credentials) { }
}
class UserRepository {
    public function findById($id) { }
    public function findByEmail($email) { }
}
class EmailService {
    public function sendWelcomeEmail($user) { }
    public function sendResetPasswordEmail($user) { }
}

数据库交互规范

1 使用预处理语句

// 必须使用PDO预处理或查询构造器
// 禁止使用字符串拼接SQL
// 使用预处理
$stmt = $pdo->prepare('SELECT * FROM users WHERE email = ?');
$stmt->execute([$email]);
// 使用查询构造器
$user = DB::table('users')
    ->where('email', $email)
    ->first();

2 数据库操作规范

// 事务处理
DB::transaction(function () {
    $order = $this->createOrder($data);
    $this->updateInventory($order->products);
    $this->chargePayment($order, $amount);
});
// 批量操作
// 避免N+1查询
$users = User::whereIn('status', ['active', 'vip'])->get();

错误处理规范

1 异常层级

// 自定义异常类
class ApiException extends \Exception {
    protected $httpCode;
    public function __construct($message, $httpCode = 400) {
        parent::__construct($message);
        $this->httpCode = $httpCode;
    }
    public function getHttpCode() {
        return $this->httpCode;
    }
}
class UserNotFoundException extends ApiException {
    public function __construct($userId) {
        parent::__construct("User with ID {$userId} not found", 404);
    }
}

2 全局异常处理

try {
    // 业务代码
} catch (UserNotFoundException $e) {
    return response()->json(['error' => $e->getMessage()], 404);
} catch (ApiException $e) {
    return response()->json(['error' => $e->getMessage()], $e->getHttpCode());
} catch (\Exception $e) {
    Log::error('Unexpected error: ' . $e->getMessage());
    return response()->json(['error' => 'Internal server error'], 500);
}

依赖注入规范

// 使用构造函数注入，避免静态调用
class OrderController extends Controller {
    private $orderService;
    private $logger;
    public function __construct(
        OrderService $orderService,
        LoggerInterface $logger
    ) {
        $this->orderService = $orderService;
        $this->logger = $logger;
    }
    public function create(Request $request) {
        // 使用注入的服务
        $order = $this->orderService->create($request->all());
        return response()->json($order);
    }
}

测试规范

// 单元测试命名规范
class UserServiceTest extends TestCase {
    public function testCreateUserWithValidData()
    {
        // Arrange
        $data = ['name' => 'John', 'email' => 'john@example.com'];
        // Act
        $user = $this->userService->createUser($data);
        // Assert
        $this->assertInstanceOf(User::class, $user);
        $this->assertEquals('John', $user->name);
    }
}

版本控制常规

1 Git提交规范

# 提交信息格式
类型(模块): 描述
# 示例
feat(auth): 添加用户登录功能
fix(order): 修复订单金额计算错误
refactor(service): 重构订单服务类
docs(api): 更新API文档
test(service): 添加服务类测试

2 分支命名

# 功能分支
feature/user-login
feature/order-export
# 修复分支
bugfix/order-total-calc
bugfix/auth-token-expire
# 发布分支
release/v1.2.0

安全规范

// 输入验证
public function login(Request $request) {
    $validated = $request->validate([
        'email' => 'required|email|max:255',
        'password' => 'required|min:8'
    ]);
}
// 防止XSS攻击
$safeHtml = htmlspecialchars($userInput, ENT_QUOTES, 'UTF-8');
// 防止CSRF（Laravel等框架默认）
// 使用CSRF token
// SQL注入防护
$query = "SELECT * FROM users WHERE id = ?";
$stmt = $db->prepare($query);
$stmt->execute([$userInput]);

性能优化规范

// 避免循环内查询
// 错误示例
foreach ($orders as $order) {
    $user = User::find($order->user_id); // N+1问题
}
// 正确示例
$userIds = array_unique(array_column($orders, 'user_id'));
$users = User::whereIn('id', $userIds)->get()->keyBy('id');
foreach ($orders as $order) {
    $user = $users[$order->user_id] ?? null;
}
// 使用缓存
$user = Cache::remember('user_' . $id, 3600, function () use ($id) {
    return User::find($id);
});
// 批量插入
DB::table('users')->insert($userData); // 而不是循环单条插入

文档规范

1 Code Review Checklist

• [ ] 代码符合PSR-12标准
• [ ] 变量和函数命名清晰且有意义
• [ ] 所有公共方法都有PHPDoc注释
• [ ] 没有重复代码（DRY原则）
• [ ] 错误处理完善
• [ ] 有适当的单元测试
• [ ] 数据库查询已优化
• [ ] 安全措施到位（SQL注入、XSS、CSRF防护）
• [ ] 性能优化合理（避免N+1、合理使用缓存）
• [ ] 文档字符串完善

---

这份规范可以根据团队实际需求进行调整，建议使用工具辅助执行,如：

• PHP_CodeSniffer：检查编码规范
• PHPStan / Psalm：静态分析
• SonarQube：代码质量平台
• PHPUnit：单元测试
• Git Hooks：提交前自动检查

需要我详细解释某个部分,或者需要补充其他方面的规范吗？