开发军规

约 961 字大约 3 分钟

2025-11-08

以下是位资深PHP工程师整理的全面开发规范（军规级），涵盖编码规范、安全、性能、数据库设计等关键方面，结合PSR标准与实战经验提炼而成。

一、基础编码规范（强制执行）

命名规范

类名：大驼峰式 + 后缀（如 UserService）
方法/函数：小驼峰式（如 getUserInfo()）
变量：小驼峰式（$userList）
常量：全大写+下划线（MAX_LIMIT = 100）
布尔值：以 is/has 开头（$isValid）

文件与目录

类文件：类名.php（UserService.php）
目录结构：遵循PSR-4自动加载（src/Service/UserService.php）
非类文件：小写+下划线（api_router.php）

语法风格

缩进：4空格（非Tab）
括号：if () { 空格规范
每行不超过 120字符
严格模式：declare(strict_types=1);
一个函数尽量不超过一个屏幕高度

二、数据库设计军规

表与字段命名

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

字段定义

主键：id（自增BIGINT）或 uuid
时间戳：created_at/updated_at（DATETIME）
布尔值：TINYINT(1) 或 BOOLEAN
金额：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优化

生产环境：composer install --no-dev --optimize-autoloader

五、架构与代码实践

单一职责原则

控制器：只处理HTTP逻辑
业务逻辑放入Service层

// 错误：控制器中写业务
class UserController {
    public function create() {
        // 直接操作DB...
    }
}

// 正确：Service分离
class UserService {
    public function createUser(array $data) { ... }
}

异常处理

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

API设计

响应格式统一：

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

六、工具链强制约束

代码质量工具

静态检查：PHP_CodeSniffer（PSR-12）
代码风格：PHP-CS-Fixer（配置PSR-12）
Git钩子：提交前自动检查

文档规范

类/方法必须含 PHPDoc：

/**
 * 用户创建服务
 * @param array $userData 用户数据数组
 * @throws InvalidArgumentException
 */
public function createUser(array $userData): User { ... }

七、新特性强制要求

类型声明

方法参数/返回值必须声明类型（PHP≥7.4）

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

返回值

禁用 array 返回，用DTO或明确结构：

class UserProfileResponse {
    public string $name;
    public int $age;
}

军规十诫（快速记忆版）

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

附：规范落地工具推荐
代码检查：PHPStan + Psalm
格式化：PHP-CS-Fixer（规则集：@PSR12+@Symfony）
安全扫描：Local PHP Security Checker（symfony check:security）
性能分析：Blackfire.io 或 XHProf

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

团队同步：使用共享配置（如 .editorconfig）确保统一。