简介

本文面向DouPHP框架的API路由解析器，系统性阐述ApiResolver类的设计理念与实现细节，覆盖RESTful路由匹配、请求验证、响应格式化、版本控制、接口限流、跨域处理、API密钥认证、中间件链设计与执行顺序、路由定义规范、错误处理标准、性能优化策略，以及与插件系统的集成方式和自定义API端点开发方法。文档以代码级事实为依据，配合图示帮助读者快速理解并扩展API能力。

项目结构

API子应用采用“声明式路由 + 分层中间件 + JSON响应”的设计：

• 入口调度：Router负责将请求交由ApiResolver解析为分发计划，再交给中央Dispatcher在中间件管道中执行。
• 路由匹配：ApiResolver使用后端声明式匹配器按URL命中、具体性排序和HTTP方法过滤，产出DispatchPlan。
• 中间件栈：默认安全头、信任代理、限流，可选用户认证；可按路由细化叠加。
• 鉴权模式：通过配置集中声明模块/动作的public/optional/required及work_required策略。
• 控制器基类：统一继承API BaseController，复用门面与服务。

graph TB
Client["客户端"] --> Router["API路由器<br/>dispatch()"]
Router --> Resolver["API解析器<br/>resolve()"]
Resolver --> Matcher["声明式匹配器<br/>BackendDeclaredMatcher"]
Resolver --> MWReg["中间件注册表<br/>compose()"]
MWReg --> MWS["中间件栈<br/>安全头/代理/限流/认证"]
Resolver --> Plan["分发计划<br/>DispatchPlan"]
Plan --> Dispatcher["中央调度器<br/>Dispatcher::run()"]
Dispatcher --> Controller["业务控制器"]
Controller --> Resp["JSON响应<br/>ApiResponse"]

核心组件

• ApiResolver：解析当前API请求为分发计划，完成URL命中、方法校验、模块可用性检查、路由参数注入、中间件栈组装。
• Router：薄壳调度器，统一处理未找到与方法不允许的JSON响应，并将有效计划交给Dispatcher执行。
• 中间件：
  • SecurityHeadersMiddleware：设置安全响应头。
  • ThrottleMiddleware：对敏感写接口与公共匿名写接口进行IP限流。
  • UserAuthMiddleware：基于Authorization Bearer令牌解析登录态，支持public/optional/required/work_required策略。
• Init：API启动流程，注册auth('api')守卫、语言与模块初始化、站点关闭检测等。
• BaseController：API控制器基类，提供会员中心导航构建等通用能力。

架构总览

API请求从入口进入后，由Router统一调度，ApiResolver根据声明式路由匹配到控制器与方法，生成包含参数与中间件栈的分发计划。随后Dispatcher在中间件管道中执行控制器逻辑，最终输出统一的JSON响应。

sequenceDiagram
participant C as "客户端"
participant R as "Router"
participant A as "ApiResolver"
participant M as "中间件栈"
participant D as "Dispatcher"
participant Ctrl as "控制器"
C->>R : HTTP 请求
R->>A : resolve(request, container)
A-->>R : DispatchPlan(命中/未找到/方法不允许)
alt 未找到或方法不允许
R-->>C : JSON 404/405
else 命中
R->>D : run(plan, container)
D->>M : 依次执行中间件
M-->>Ctrl : 通过校验的请求
Ctrl-->>D : 业务结果
D-->>R : Response
R-->>C : JSON 响应
end

详细组件分析

ApiResolver：API路由解析器

• 设计要点
  • 使用声明式匹配器按URL命中、具体性排序与HTTP方法过滤，返回命中信息或状态。
  • 对会员衍生模块进行可用性闸控，避免容器反射到不可用模块。
  • 解析目标方法与参数，注入基础URL、路由信息与路由参数。
  • 组装中间件栈：默认安全头、信任代理、限流；当开启features.user时追加用户认证。
• 关键行为
  • 未命中：返回notFound计划，由Router渲染404 JSON。
  • 方法不被接受：返回methodNotAllowed计划，附带允许的方法列表。
  • 成功命中：返回包含控制器FQCN、方法名、参数与中间件的DispatchPlan。

flowchart TD
Start(["开始"]) --> Match["声明式匹配"]
Match --> |未命中| NotFound["返回 notFound"]
Match --> |方法不允许| MethodNotAllowed["返回 methodNotAllowed"]
Match --> |命中| BuildPlan["构建参数与中间件栈"]
BuildPlan --> ReturnPlan["返回 DispatchPlan"]
NotFound --> End(["结束"])
MethodNotAllowed --> End
ReturnPlan --> End

Router：API调度器

• 职责
  • 获取Request与Container，调用ApiResolver解析。
  • 对未找到与方法不允许直接返回JSON错误。
  • 将有效计划交给Dispatcher执行，若已产生Response则直接返回。
• 错误处理
  • 404：Not Found JSON。
  • 405：Method Not Allowed JSON，携带允许方法列表。

sequenceDiagram
participant R as "Router"
participant A as "ApiResolver"
participant D as "Dispatcher"
R->>A : resolve()
A-->>R : DispatchPlan
alt isNotFound
R-->>R : ApiResponse : : error(404)
else isMethodNotAllowed
R-->>R : ApiResponse : : error(405, allow)
else 命中
R->>D : run(plan)
D-->>R : Response or null
end

中间件链设计与执行顺序

• 默认栈顺序（由ApiResolver默认别名决定）
  1. security_headers：设置安全响应头。
  2. trust_proxy：信任代理（如反向代理IP）。
  3. throttle：对敏感写接口与公共匿名写接口进行IP限流。
  4. user_auth：仅在features.user开启时加入，基于Bearer令牌解析登录态。
• 路由级细化：可在路由声明中附加额外中间件，叠加到全局默认栈之上。
• 鉴权模式：通过middleware.php集中声明module/sub/action级别的public/optional/required与工作端work_required策略。

flowchart LR
In["请求进入"] --> SH["安全头"]
SH --> TP["信任代理"]
TP --> TH["限流"]
TH --> UA{"启用用户认证?"}
UA --> |是| Auth["用户认证"]
UA --> |否| Next["继续"]
Auth --> Next
Next --> Out["到达控制器"]

UserAuthMiddleware：用户认证中间件

• 功能
  • 从Authorization: Bearer <token>提取令牌，调用auth('api')->resolveUserContext解析上下文。
  • 将解析结果注入到auth('api')，供后续控制器读取当前用户与工作端身份。
  • 拒绝未认证或无工作端权限时，发送401/403 JSON并终止。
• 鉴权模式
  • public：不尝试解析登录态。
  • optional：尝试解析，失败不拦截。
  • required：必须登录。
  • work_required：在required基础上额外校验工作端身份。

sequenceDiagram
participant MW as "UserAuthMiddleware"
participant Auth as "auth('api')"
participant Req as "Request"
MW->>Req : bearerToken()
MW->>Auth : resolveUserContext(token)
Auth-->>MW : {ok, context}
alt ok
MW->>Auth : hydrate(context)
MW-->>Next : 放行
else 未认证
MW-->>Client : 401 JSON
end

ThrottleMiddleware：接口限流中间件

• 功能
  • 针对登录、注册、短信验证码、公共匿名写接口与防伪查询等路径，按IP进行限流。
  • 超限返回429 JSON，并设置Retry-After头。
• 配额策略
  • 通过路由键（module/action或module/sub/action）映射到max/window限制。
  • 候选匹配优先级从高到低，精确命中优先。

flowchart TD
Enter["进入限流"] --> Key["计算路由键"]
Key --> Find{"是否命中配额?"}
Find --> |否| Pass["放行"]
Find --> |是| Check["计数窗口内次数"]
Check --> Over{"超过上限?"}
Over --> |否| Pass
Over --> |是| Reject["返回 429 + Retry-After"]

SecurityHeadersMiddleware：安全响应头中间件

• 功能
  • 设置基线安全响应头（如X-Frame-Options、X-Content-Type-Options等），行为委托基类实现。
• 适用场景
  • 所有API响应均受保护，防止点击劫持、MIME嗅探等风险。

路由定义规范

• 入口形态：/api/?route=module[/id][/action]，数字段即id。
• 声明式路由：在api/route/*.php中使用Route::group、Route::resource等方法定义。
• 命名空间与分组：统一使用name('api.')分组，便于命名与调试。
• 子控制器：通过prefix与sub组合划分不同角色（如user/cart、order/work）。
• 示例
  • index：首页API。
  • user：会员相关接口，含weixin子控制器与work/contact子控制器。
  • product：商品浏览与核销端CRUD。
  • order：订单、购物车、结算、收银台、核销端等多角色接口。

错误处理标准

• 未找到：404 JSON，消息为Not Found。
• 方法不允许：405 JSON，携带allow字段列出允许方法。
• 未认证：401 JSON，消息来自语言包login_timeout。
• 无工作端权限：403 JSON，消息来自语言包work_no_permission。
• 限流：429 JSON，设置Retry-After头，消息来自语言包request_throttled。
• 站点关闭：503 JSON，消息site_closed。

版本控制、跨域处理、API密钥认证

• 版本控制
  • 当前实现未内置版本前缀；可通过路由分组与命名约定实现（例如在路由文件中按v1/v2分别声明）。
• 跨域处理
  • 未在API中间件中显式实现CORS；如需跨域，可在反向代理层或扩展中间件中添加Access-Control-*头。
• API密钥认证
  • 当前认证基于Authorization: Bearer令牌；如需API密钥，可结合TrustProxyMiddleware与自定义中间件在边界处校验。

与插件系统的集成方式

• 初始化阶段加载核心扩展文件include/core.load.php，用于插件钩子与扩展机制。
• 通过ProviderRegistry注册服务契约（如LanguageContract、PluginServiceContract），使插件可插拔地提供实现。
• 在Init中按需实例化服务（如PricingService、MiniprogramCatalogQuery），供业务控制器使用。

如何开发自定义API端点

• 步骤
  1. 在api/controller下创建控制器类，继承BaseController。
  2. 在api/route下新增或编辑路由文件，使用Route::group/resource声明GET/POST/PUT/DELETE等。
  3. 在api/init/middleware.php中登记鉴权模式（public/optional/required/work_required）。
  4. 如需限流，在ThrottleMiddleware的配额表中添加路由键与限制。
  5. 控制器内通过helper/门面访问DB、auth('api')、Config等服务。
• 最佳实践
  • 保持路由简洁，合理使用prefix与sub区分角色。
  • 明确鉴权级别，避免新模块静默以匿名上线。
  • 对写操作增加限流与签名校验（结合代理层或自定义中间件）。

依赖关系分析

• 组件耦合
  • Router依赖ApiResolver与Dispatcher，低耦合、高内聚。
  • ApiResolver依赖声明式匹配器、中间件注册表与方法解析器，职责清晰。
  • 中间件之间通过顺序串联，互不感知，易于替换与扩展。
• 外部依赖
  • Container：对象生命周期管理。
  • Config：特性开关（如features.user）与系统配置。
  • Module：模块可用性检查与按需加载。
• 潜在循环依赖
  • 通过抽象基类与注册表解耦，未见循环引用迹象。

graph LR
Router --> ApiResolver
ApiResolver --> Matcher["BackendDeclaredMatcher"]
ApiResolver --> MWReg["MiddlewareRegistry"]
ApiResolver --> MethodResolver["MethodResolver"]
Router --> Dispatcher
Dispatcher --> Controllers["控制器"]
Controllers --> Services["服务/门面"]

性能考量

• 路由匹配
  • 使用声明式匹配器并按具体性排序，减少回溯与分支判断。
• 中间件栈
  • 默认栈轻量（安全头、代理、限流），认证仅在必要时加入。
  • 限流基于IP与窗口计数，避免昂贵计算。
• 响应格式
  • 统一JSON输出，减少模板渲染开销。
• 建议
  • 合理拆分路由，避免过深嵌套。
  • 对高频读接口考虑缓存（如Redis）与数据库索引优化。
  • 在高并发场景下评估限流阈值与存储后端性能。

故障排查指南

• 404 Not Found
  • 检查路由文件是否正确声明，URL与HTTP方法是否匹配。
  • 确认模块可用性与features配置。
• 405 Method Not Allowed
  • 检查路由是否仅声明了部分HTTP方法，确保调用方法在允许列表中。
• 401 Unauthorized
  • 检查Authorization头是否携带正确令牌，确认features.user已开启且user模块就位。
• 403 Forbidden
  • 检查work_required策略是否满足，确认工作端身份存在。
• 429 Rate Limited
  • 检查对应路由键是否在限流表中，调整max/window或降低请求频率。
• 503 Site Closed
  • 检查站点维护开关，临时关闭后将恢复。

结论

DouPHP的API路由解析器以声明式路由与分层中间件为核心，实现了清晰的职责分离与可扩展的鉴权、限流与安全策略。ApiResolver作为中枢，将URL命中、方法校验、模块可用性检查与中间件装配整合为一，Router统一错误处理与响应格式。通过集中化的鉴权模式与限流策略，开发者可以高效地定义与维护API端点，同时保证安全性与性能。

附录

• 常用中间件别名
  • security_headers：安全响应头。
  • trust_proxy：信任代理。
  • throttle：限流。
  • user_auth：用户认证（需features.user开启）。
• 鉴权模式
  • public：匿名可访问。
  • optional：尝试解析登录态，失败不拦截。
  • required：必须登录。
  • work_required：在required基础上校验工作端身份。