简介

本指南面向DouPHP项目的开发者与维护者，聚焦SQL注入防护。内容涵盖ORM系统的安全使用方式、参数化查询的正确用法、输入验证与过滤的最佳实践、常见漏洞规避方法、数据库查询安全模式、存储过程的安全使用建议，以及安全审计与漏洞检测流程。文档中的示例均以“代码片段路径”形式给出，便于在仓库中快速定位实现细节。

项目结构

本项目将数据访问能力集中在基础设施层与ORM层：

• ORM层：提供模型（Model）、查询构造器（Builder）与集合（Collection），封装链式查询、预加载、全局作用域等高级特性。
• 基础设施层：提供数据库连接（Connection）与闭包查询构建器（QueryBuilder），负责参数绑定、类型推断与最终SQL执行。
• 配置层：集中管理数据库连接信息与系统开关。

graph TB
A["业务代码<br/>控制器/服务"] --> B["ORM 查询构造器<br/>Builder"]
B --> C["ORM 模型基类<br/>Model"]
C --> D["数据库连接<br/>Connection"]
D --> E["MySQL 服务器"]
A --> F["闭包查询构建器<br/>QueryBuilder"]
F --> D

核心组件

• ORM 查询构造器（Builder）：提供链式查询接口，透传到底层 Connection；对主键查找进行标量校验，防止误用导致的全表扫描或错误条件。
• ORM 模型（Model）：统一读写契约，支持批量填充、属性转换、事件、全局作用域、预加载等；对外暴露静态入口以简化调用。
• 数据库连接（Connection）：封装 mysqli 操作，设置严格SQL模式，提供表名前缀处理、事务、分页、聚合等方法；内部维护链式查询状态与参数绑定。
• 闭包查询构建器（QueryBuilder）：用于复杂WHERE/HAVING条件的组合，自动收集绑定参数与类型，避免字符串拼接。

架构总览

下图展示从业务请求到数据库执行的完整链路，强调参数化与类型绑定如何阻断SQL注入。

sequenceDiagram
participant U as "用户/客户端"
participant C as "控制器/服务"
participant M as "ORM 模型(Model)"
participant B as "ORM 查询构造器(Builder)"
participant Q as "闭包查询构建器(QueryBuilder)"
participant DB as "数据库连接(Connection)"
participant S as "MySQL 服务器"
U->>C : "发起请求"
C->>M : "调用 Model : : where()/with() 等"
M->>B : "newQuery() 并转发方法"
B->>Q : "解析 where/having 条件并收集绑定参数"
B->>DB : "select()/paginate() 等终结方法"
DB->>S : "执行参数化语句"
S-->>DB : "返回结果集"
DB-->>B : "结果集"
B-->>M : "水合为 Model/Collection"
M-->>C : "业务对象"
C-->>U : "响应"

详细组件分析

ORM 查询构造器（Builder）安全要点

• 主键查找保护：find()/whereKey() 强制标量主键，拒绝空值、数组、对象等非法输入，避免退化为全表扫描或错误条件。
• 全局作用域：在读取路径（get/paginate/first/find）应用全局scope，确保软删除、可见性等策略一致生效；聚合方法通过白名单控制是否应用全局scope。
• 链式透传：__call将未命中方法透传到底层Connection，保证查询一致性同时限制危险操作。

flowchart TD
Start(["进入 find/whereKey"]) --> Check["校验主键是否为标量"]
Check --> |是| ApplyWhere["添加 WHERE 主键=值"]
Check --> |否| ThrowErr["抛出参数异常"]
ApplyWhere --> Next["继续链式查询"]
ThrowErr --> End(["终止"])
Next --> End

ORM 模型（Model）安全要点

• 统一入口：静态方法转发至查询构造器，减少直接拼接SQL的机会。
• 批量写入：create/fill 结合可写字段白名单（fillable）控制写入范围，降低恶意字段注入风险。
• 事件与全局作用域：通过事件与全局scope统一处理逻辑删除、租户隔离等安全相关约束。

数据库连接（Connection）安全要点

• 严格SQL模式：连接时启用STRICT_TRANS_TABLES，避免静默截断导致的脏数据入库。
• 表名前缀与转义：tableName()统一加前缀与反引号；escapeString()用于必要时的字符串转义。
• 事务与保存点：beginTransaction/commit/rollback支持嵌套，保证复杂操作的原子性与一致性。
• 链式查询状态：table/join/order/limit等维护内部状态，最终由select/paginate等终结方法生成SQL并执行。

闭包查询构建器（QueryBuilder）安全要点

• 条件解析：where/having支持AND/OR连接，支持IN/NOT IN与IS NULL/IS NOT NULL等语义。
• 参数绑定：自动收集绑定参数与类型（i/d/s），避免字符串拼接，从根本上阻断SQL注入。
• 子查询：支持闭包内构建子查询，合并条件与绑定参数，保持安全性与可读性。

flowchart TD
WStart(["调用 where/having"]) --> Parse["解析字段/操作符/值"]
Parse --> Type{"操作符类型"}
Type --> |IN/NOT IN| BindArr["遍历数组逐个绑定参数"]
Type --> |普通| BindOne["绑定单个参数"]
Type --> |IS NULL/IS NOT NULL| NoBind["无需绑定参数"]
BindArr --> Collect["收集绑定参数与类型"]
BindOne --> Collect
NoBind --> Collect
Collect --> Return(["返回$this 继续链式"])

依赖关系分析

• Builder依赖Model获取表名、主键、全局作用域与默认预加载；并通过Model.getConnection()获取底层Connection。
• QueryBuilder独立于ORM，专注于WHERE/HAVING条件解析与参数绑定，供复杂查询场景使用。
• Connection作为唯一数据库访问入口，负责连接、字符集、SQL模式、事务与最终执行。

classDiagram
class Builder {
+get()
+first()
+find(id, field)
+paginate(...)
+orderBy(field, direction)
+with(relations)
}
class Model {
+query()
+create(attributes)
+destroy(id)
+getConnection()
}
class Connection {
+table(table)
+join(table, condition)
+order(expr)
+limit(n)
+select()
+paginate(...)
+beginTransaction()
+commit()
+rollback()
}
class QueryBuilder {
+where(field, op, value)
+having(field, op, value)
+getWhere()
+getBind()
+getBindTypes()
}
Builder --> Model : "使用"
Builder --> Connection : "透传查询"
QueryBuilder --> Connection : "参数绑定"

性能与安全注意事项

• 优先使用ORM的链式查询与参数化绑定，避免手动拼接SQL。
• 使用whereKey/find进行主键查找，确保传入标量；必要时使用whereIn批量查询以减少往返。
• 合理使用全局作用域与预加载，避免N+1查询与不必要的数据暴露。
• 开启严格SQL模式，防止隐式类型转换与截断带来的数据不一致。
• 对IN/NOT IN等集合操作，确保传入非空数组；空数组将被忽略以避免意外全表扫描。
• 在调试模式下记录最后执行的SQL与参数，便于问题定位；生产环境关闭敏感信息输出。

故障排查指南

• 连接失败：检查主机、端口、用户名、密码与数据库名是否正确；确认mysqli扩展已启用。
• 字符集问题：连接时尝试utf8mb4，不支持则降级到utf8；确保客户端与服务端字符集一致。
• SQL模式报错：严格模式下超长或溢出会抛错，需修正数据类型或长度；历史零日期行可能无法读写。
• 事务回滚：嵌套事务使用保存点，确保最外层提交或回滚；异常时及时回滚避免部分更新。
• 调试日志：开启debug_mode后记录查询与错误；生产环境关闭以避免信息泄漏。

结论

DouPHP通过ORM与基础设施层的参数化查询、类型绑定与严格SQL模式，提供了坚实的SQL注入防护基础。开发者应遵循以下原则：

• 始终使用ORM或QueryBuilder进行数据访问，避免拼接SQL。
• 对主键与ID进行标量校验，使用whereKey/find。
• 利用全局作用域与预加载统一安全策略与性能优化。
• 在生产环境关闭调试输出，仅保留必要的错误摘要。
• 定期审计查询代码，关注IN/NOT LIKE/LIKE等易被滥用操作符的使用。

附录：安全实践清单与审计要点

• 参数化查询
  • 使用ORM的where/having与QueryBuilder的绑定机制，避免字符串拼接。
  • 参考路径：core/infra/database/QueryBuilder.php:111-185
• 主键查找保护
  • 使用find/whereKey并确保传入标量。
  • 参考路径：core/orm/Builder.php:232-325
• 全局作用域
  • 在读取路径应用全局scope，确保软删除、可见性等策略一致。
  • 参考路径：core/orm/Builder.php:120-143
• 严格SQL模式
  • 连接时启用STRICT_TRANS_TABLES，避免脏数据入库。
  • 参考路径：core/infra/database/Connection.php:184-189
• 输入验证与过滤
  • 在业务层对输入进行类型与范围校验；对IN/NOT IN确保非空数组。
  • 参考路径：core/infra/database/QueryBuilder.php:156-159
• 存储过程安全使用
  • 若必须使用存储过程，请通过参数化调用，避免动态拼接过程名或参数。
  • 建议在ORM或连接层封装统一调用入口，集中校验与日志记录。
• 安全审计与漏洞检测
  • 审查所有where/having/join条件，确保无字符串拼接。
  • 使用调试模式记录最后SQL与参数，核对绑定情况。
  • 参考路径：core/infra/database/Connection.php:219-234