开发军规

约 696 字大约 2 分钟

2025-11-08

本文结合 PSR 标准与实战经验，整理 PHP 开发核心规范。

一、编码规范

命名规范

类型	规范	示例
类名	大驼峰 + 后缀	`UserService`
方法/函数	小驼峰	`getUserInfo()`
变量	小驼峰	`$userList`
常量	全大写 + 下划线	`MAX_LIMIT = 100`
布尔变量	以 `is`/`has` 开头	`$isValid`

文件与目录

类文件命名：类名.php，遵循 PSR-4 自动加载
非类文件：小写 + 下划线（api_router.php）
缩进：4 空格（非 Tab）
每行不超过 120 字符
入口文件首部添加 declare(strict_types=1);

二、数据库规范

命名

表名/字段名：小写 + 下划线（user_order、created_at）
禁用 SQL 保留字（order → user_order）

字段定义

主键：id（BIGINT 自增）或 uuid
时间戳：created_at / updated_at（DATETIME）
布尔值：TINYINT(1)
金额：DECIMAL(10,2)，禁止使用 Float

索引命名

主键：pk_table_name
唯一索引：uk_table_name_field
普通索引：idx_table_name_field

三、安全规范

SQL 注入

强制使用预处理语句（PDO / ORM）：

// 错误
$sql = "SELECT * FROM users WHERE id = $id";

// 正确
$stmt = $pdo->prepare("SELECT * FROM users WHERE id = ?");
$stmt->execute([$id]);

XSS 防护

输出到 HTML 前转义：htmlspecialchars($str, ENT_QUOTES)
富文本：使用 HTMLPurifier 过滤

CSRF 防护

表单必须包含 CSRF Token（框架内置或手动实现）。

密码存储

必须使用 password_hash() + password_verify()，禁止 MD5/SHA1。

四、性能优化

循环内避免 DB 查询（用 WHERE IN 替代）
大数组处理使用生成器（yield）
生产环境关闭 display_errors
高频读操作使用 Redis/Memcached
启用 OPcache
生产环境：composer install --no-dev --optimize-autoloader

五、架构实践

分层设计

Controller：仅处理 HTTP 逻辑
Service：业务逻辑放入 Service 层

// Controller 只负责转发
class UserController {
    public function create(UserService $service) {
        return $service->createUser($this->request->all());
    }
}

异常处理

使用自定义异常类（如 UserNotFoundException）
禁止直接使用 die() 或 exit()

API 响应格式

{
    "code": 200,
    "msg": "success",
    "data": { }
}

六、类型声明

PHP 7.4+ 强制使用类型声明：

public function calculate(int $a, float $b): float { ... }

返回值优先使用 DTO 或明确结构，避免裸 array。

七、工具链

用途	工具
代码风格	PHP-CS-Fixer（`@PSR12`）
静态分析	PHPStan / Psalm
安全扫描	`symfony check:security`
性能分析	Blackfire.io / XHProf

速记清单

禁止 SQL 拼接（必须预处理）
禁止输出未过滤的用户数据
禁用 eval() / create_function()
所有异常必须日志记录
PHP 版本 ≥ 8.1
生产环境关闭错误显示
密码必须 password_hash()
数组使用短语法 []
Composer 包定期检查安全更新
核心逻辑代码覆盖率 ≥ 70%

执行原则：规范通过 CI/CD 自动化检查，人工 Review 作为第二防线。新项目 100% 遵守，老系统增量重构。