开发军规

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

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

  1. 命名规范
  • 类名：大驼峰式 + 后缀（如 UserService）
  • 方法/函数：小驼峰式（如 getUserInfo()）
  • 变量：小驼峰式（$userList）
  • 常量：全大写+下划线（MAX_LIMIT = 100）
  • 布尔值：以 is/has 开头（$isValid）
  1. 文件与目录
  • 类文件：类名.php（UserService.php）
  • 目录结构：遵循PSR-4自动加载（src/Service/UserService.php）
  • 非类文件：小写+下划线（api_router.php）
  1. 语法风格
  • 缩进：4空格（非Tab）
  • 括号：if () { 空格规范
  • 每行不超过 120字符
  • 严格模式：declare(strict_types=1);
  • 一个函数尽量不超过一个屏幕高度

二、数据库设计军规

  1. 表与字段命名
  • 表名：小写+下划线（user_order）
  • 字段名：小写+下划线（created_at）
  • 禁用保留字（如 order → user_order）
  1. 字段定义
  • 主键：id（自增BIGINT）或 uuid
  • 时间戳：created_at/updated_at（DATETIME）
  • 布尔值：TINYINT(1) 或 BOOLEAN
  • 金额：DECIMAL(10,2) 禁止Float
  1. 索引规范
  • 主键命名：pk_table_name
  • 唯一索引：uk_table_name_field
  • 普通索引：idx_table_name_field

三、安全防御铁律

  1. SQL注入
  • 强制使用 预处理语句（PDO或ORM）
// 错误示例
$sql = "SELECT * FROM users WHERE id = $id"; 

// 正确做法
$stmt = $pdo->prepare("SELECT * FROM users WHERE id = ?");
$stmt->execute([$id]);
  1. XSS防护
  • 输出到HTML前必须转义：htmlspecialchars($str, ENT_QUOTES)
  • 富文本：用 HTMLPurifier 过滤
  1. CSRF防护
  • 表单必须含CSRF Token（框架内置或手动实现）
  1. 密码存储
  • 必须 password_hash() + password_verify()
  • 禁止MD5/SHA1

四、性能优化要点

  1. 内存与耗时
  • 循环内避免DB查询（用 WHERE IN 替代）
  • 大数组处理用生成器（yield）
  • 错误级别：生产环境关闭 display_errors
  1. 缓存策略
  • 高频读操作：Redis/Memcached
  • 文件缓存用OPcache加速
  1. Composer优化
  • 生产环境：composer install --no-dev --optimize-autoloader

五、架构与代码实践

  1. 单一职责原则
  • 控制器：只处理HTTP逻辑
  • 业务逻辑放入Service层
// 错误：控制器中写业务
class UserController {
    public function create() {
        // 直接操作DB...
    }
}

// 正确：Service分离
class UserService {
    public function createUser(array $data) { ... }
}
  1. 异常处理
  • 自定义异常类（如 UserNotFoundException）
  • 禁止直接 die() 或 exit()
  1. API设计
  • 响应格式统一：
{
    "code": 200,
    "msg": "success",
    "data": { }
}

六、工具链强制约束

  1. 代码质量工具
  • 静态检查：PHP_CodeSniffer（PSR-12）
  • 代码风格：PHP-CS-Fixer（配置PSR-12）
  • Git钩子：提交前自动检查
  1. 文档规范
  • 类/方法必须含 PHPDoc：
/**
 * 用户创建服务
 * @param array $userData 用户数据数组
 * @throws InvalidArgumentException
 */
public function createUser(array $userData): User { ... }

七、新特性强制要求

  1. 类型声明
  • 方法参数/返回值必须声明类型（PHP≥7.4）
public function calculate(int $a, float $b): float { ... }
  1. 返回值
  • 禁用 array 返回，用DTO或明确结构：
class UserProfileResponse {
    public string $name;
    public int $age;
}

军规十诫（快速记忆版）

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

附：规范落地工具推荐

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

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

  1. 团队同步：使用共享配置（如 .editorconfig）确保统一。
Last Updated:
Contributors: hqdxhyf