简介

本文件为 DouPHP 的 API 端 REST 接口层文档，面向移动端开发者、小程序开发者与第三方集成商。内容覆盖：

• RESTful 风格路由、HTTP 方法与 URL 模式
• 认证授权机制（Bearer Token、鉴权中间件、权限策略）
• 公共模块接口规范（用户、商品、订单等）
• 请求/响应格式、错误码与错误处理
• 版本管理、向后兼容性与限流策略
• 测试方法与调试建议

API 端作为统一的服务出口，为小程序、移动应用、单页应用（SPA）以及第三方系统提供标准化的 JSON 接口服务。

项目结构

API 入口统一通过 api/index.php 启动，使用声明式路由与分层中间件完成请求分发。核心路径要点：

• 入口：api/index.php
• 路由解析：ApiResolver、Router
• 中间件：安全头、代理信任、限流、用户认证
• 控制器：按模块划分（user、product、order 等）
• 鉴权门面：Auth（基于不透明 token）
• 配置：应用密钥、调试开关等

graph TB
Client["客户端<br/>小程序/移动应用/第三方"] --> Entry["API 入口<br/>api/index.php"]
Entry --> Router["路由调度<br/>Router"]
Router --> Resolver["路由解析<br/>ApiResolver"]
Resolver --> MW["中间件栈<br/>SecurityHeaders / TrustProxy / Throttle / UserAuth"]
MW --> Controller["业务控制器<br/>UserController / ProductController / OrderController"]
Controller --> Service["服务层/门面<br/>DB / auth('api') / 业务服务"]
Service --> Response["统一响应<br/>ApiResponse"]

核心组件

• 入口与异常处理：统一捕获未处理异常并返回 JSON 500；支持站点调试时输出详细堆栈。
• 路由系统：以 ?route=module[/sub][/action] 形式进入，匹配后产出 DispatchPlan，交由中央 Dispatcher 执行。
• 中间件栈：默认包含安全头、代理信任、限流；当启用会员功能时自动加入用户认证中间件。
• 鉴权门面：基于不透明 token 的 Guard，提供身份注入、上下文解析、登录态检查等方法。
• 控制器基类：封装 API 端通用能力（如会员中心导航构建）。

架构总览

请求从入口进入，经路由解析命中控制器与方法，中间件在管道中依次执行（安全头→代理信任→限流→用户认证），最终由控制器调用服务并返回统一 JSON 响应。

sequenceDiagram
participant C as "客户端"
participant E as "入口 api/index.php"
participant R as "Router"
participant A as "ApiResolver"
participant M as "中间件栈"
participant Ctrl as "控制器"
participant S as "服务/门面"
participant Resp as "ApiResponse"
C->>E : HTTP 请求
E->>R : dispatch()
R->>A : resolve(request, container)
A-->>R : DispatchPlan(含中间件列表)
R->>M : 执行中间件管道
M->>Ctrl : 命中控制器方法
Ctrl->>S : 调用服务/门面
S-->>Ctrl : 数据/结果
Ctrl->>Resp : success()/error()
Resp-->>C : JSON 响应

详细组件分析

认证与授权机制

• 认证方式：Bearer Token（Authorization: Bearer <token>）
• 令牌生命周期：登录成功后签发；退出时吊销；过期或无效则拒绝访问
• 鉴权中间件：UserAuthMiddleware 负责从请求头提取 token，调用 auth('api')->resolveUserContext 解析上下文并注入到当前请求
• 权限策略：middleware.php 中定义各模块/动作的鉴权级别（public、optional、required），以及 work_required 子策略用于工作端校验
• 未认证/无权限：分别返回 401/403 JSON 错误

flowchart TD
Start(["请求进入"]) --> Extract["提取 Authorization: Bearer"]
Extract --> Resolve{"auth('api')->resolveUserContext"}
Resolve --> |ok| Inject["注入用户与工作端上下文"]
Resolve --> |not ok| Reject401["返回 401 未登录"]
Inject --> CheckMode{"鉴权模式 required?"}
CheckMode --> |否| Next["继续后续中间件/控制器"]
CheckMode --> |是| WorkCheck{"是否要求工作端身份?"}
WorkCheck --> |否| Next
WorkCheck --> |是| HasWork{"hasWorkIdentity?"}
HasWork --> |是| Next
HasWork --> |否| Reject403["返回 403 无工作端权限"]

限流策略

• 适用场景：登录/注册/找回密码/短信验证码下发、匿名写接口（留言/咨询/邮件订阅）、防伪查询、LLM 对话等
• 规则：按 module/sub/action 维度配置配额（次数/时间窗口），超限返回 429 并附带 Retry-After
• 扩展：可在 ThrottleMiddleware 中新增路由键与配额

flowchart TD
Req["请求到达"] --> Match["匹配限流规则"]
Match --> Found{"找到规则?"}
Found --> |否| Pass["放行"]
Found --> |是| Count["计数统计"]
Count --> Over{"超过配额?"}
Over --> |否| Pass
Over --> |是| Reject["返回 429 + Retry-After"]

用户管理模块（user）

• 主要路由：
  • GET/POST user/*：会员中心首页、注册、登录、手机登录、密码重置、资料编辑、修改密码、退出、SNS 绑定、地区数据、文件上传/删除、登录态检查、头像上传
  • GET user/weixin/get_phone、GET user/weixin/login、POST user/weixin/pay：微信相关能力
  • GET user/work/index：工作端索引
  • GET/POST user/contact/*：联系人管理
• 典型流程（登录）：
  • 客户端提交用户名/密码或手机号+验证码
  • 控制器验证凭据，成功则签发 token 并返回用户信息
  • 后续请求携带 Authorization: Bearer <token> 进行鉴权

sequenceDiagram
participant App as "客户端"
participant UC as "UserController"
participant LS as "LoginService"
participant UA as "UserAuthService"
participant Auth as "auth('api')"
App->>UC : POST user/login_post
UC->>LS : validateLoginCredentials(...)
LS-->>UC : 结果(用户/字段)
UC->>UA : login(user, field)
UA-->>UC : token
UC-->>App : {user, dou.auth.is_work}
App->>UC : 后续请求带 Authorization : Bearer
UC->>Auth : id()/check()
Auth-->>UC : 已登录上下文

商品管理模块（product）

• 主要路由：
  • GET product：商品列表（支持分类、品牌、排序、分页）
  • GET product/{id}：商品详情
  • GET product/attribute_list：属性计算
  • product/work/*：核销端增删改查（store/update/destroy）
• 典型流程（列表）：
  • 解析分类 ID、归档参数、页码、品牌、排序
  • 构建商品列表数据并返回

flowchart TD
In["GET product"] --> Parse["解析分类/归档/页码/品牌/排序"]
Parse --> Build["构建商品列表数据"]
Build --> Return["返回 ApiResponse.success(data)"]

订单处理模块（order）

• 主要路由：
  • GET order：购物车首页（需登录）
  • order/user/*：我的订单（index/show/cancel）
  • order/cart/*：购物车资源操作（cart_number/store/update/destroy）
  • order/checkout/*：结算流程（index/checkout_post/success/change_shipping/use_coupon）
  • order/cashier/*：收银台（pay/pay_evidence）
  • order/work/*：核销端（index/show/order_cancel/pay_check/tracking）
• 典型流程（购物车）：
  • 校验登录态，获取用户 ID
  • 读取购物车数据并返回

sequenceDiagram
participant App as "客户端"
participant OC as "OrderController"
participant OS as "OrderService"
App->>OC : GET order
OC->>OC : mustLoginUserId()
OC->>OS : getCart(userId)
OS-->>OC : cart
OC-->>App : {title, cart}

依赖关系分析

• 入口依赖路由与中间件：入口将 route 字符串写入 Request，随后由 Router 与 ApiResolver 解析并组装中间件栈
• 中间件依赖配置：鉴权模式与 work_required 策略来自 middleware.php
• 控制器依赖服务与门面：通过依赖注入或服务门面访问业务逻辑
• 鉴权门面依赖 token 服务：ApiTokenService 负责 token 的解析与吊销

graph LR
Entry["api/index.php"] --> Router["Router"]
Router --> Resolver["ApiResolver"]
Resolver --> MW["中间件(限流/认证)"]
MW --> Controllers["控制器"]
Controllers --> Facade["Auth 门面"]
Facade --> TokenSvc["ApiTokenService"]

性能与限流

• 限流：对高频敏感接口实施 IP 维度的限流，避免滥用与刷量
• 缓存：可结合服务层与存储层优化热点数据（如商品列表、分类树）
• 数据库：合理使用索引与分页，减少全表扫描
• 响应体：仅返回必要字段，降低网络开销

故障排查指南

• 未捕获异常：入口统一捕获并返回 JSON 500；开启站点调试时可输出详细堆栈
• 鉴权失败：检查 Authorization 头是否正确、token 是否有效、鉴权模式配置是否合理
• 限流触发：关注 429 响应与 Retry-After 头，调整调用频率或申请更高配额
• 路由未命中：确认 route 参数格式与模块/动作是否存在

结论

DouPHP API 端采用声明式路由与分层中间件架构，提供统一的认证授权、限流与安全头策略。通过模块化控制器与服务层解耦，便于扩展与维护。建议在生产环境关闭调试、严格配置鉴权模式与限流规则，并结合监控与日志完善可观测性。

附录：公共API参考

通用约定

• 基础URL：/api/index.php?route=模块/子模块/动作
• 认证：需要认证的接口需在 Authorization 头携带 Bearer <token>
• 响应格式：统一使用 ApiResponse 返回 JSON，包含状态码与消息
• 错误码：使用 ApiCodes 中的标准错误码（如未登录、未找到、服务器错误、速率限制等）

用户模块（user）

• GET/POST user/register：注册表单/提交
• GET/POST user/login：登录表单/提交
• GET/POST user/login_phone：手机登录表单/提交
• GET/POST user/password_reset：密码重置表单/提交
• GET/POST user/edit：资料编辑表单/提交
• GET/POST user/password：修改密码表单/提交
• POST user/logout：退出登录（吊销 token）
• GET/POST user/sns：第三方账号管理/引导
• GET user/area：省市区数据
• POST user/filebox：文件上传
• POST user/filedel：文件删除
• GET user/check_login_state：登录态检查
• POST user/upload_avatar：上传头像
• GET user/weixin/get_phone：微信获取手机号
• GET user/weixin/login：微信登录
• POST user/weixin/pay：微信支付

示例（登录）

• 请求：POST /api/index.php?route=user/login_post
• 请求体：username、password（或 mobile、verification、verification_data）
• 响应：{ user, dou: { auth: { is_work } } }

示例（退出）

• 请求：POST /api/index.php?route=user/logout
• 头部：Authorization: Bearer <token>
• 响应：空数据

商品模块（product）

• GET product：商品列表（支持 category_id、brand_id、by、sort、page、year、month）
• GET product/{id}：商品详情
• GET product/attribute_list：属性计算
• POST/PUT/DELETE product/work/*：核销端增删改

示例（列表）

• 请求：GET /api/index.php?route=product&id=分类ID&page=1&brand_id=品牌ID&by=排序字段&sort=asc/desc
• 响应：{ title, category_id, product_category, ... }

订单模块（order）

• GET order：购物车首页（需登录）
• GET/POST order/user/*：我的订单（index/show/cancel）
• GET/POST/PUT/DELETE order/cart/*：购物车资源（cart_number/store/update/destroy）
• POST order/checkout/*：结算流程（index/checkout_post/success/change_shipping/use_coupon）
• GET/POST order/cashier/*：收银台（pay/pay_evidence）
• GET/POST order/work/*：核销端（index/show/order_cancel/pay_check/tracking）

示例（购物车）

• 请求：GET /api/index.php?route=order
• 头部：Authorization: Bearer <token>
• 响应：{ title, cart }

版本管理与兼容性

• 路由命名空间：所有路由名称以 api. 前缀组织，便于未来版本化（如 api.v1.*）
• 向后兼容：新增动作优先以 optional/public 策略上线，逐步收紧至 required
• 变更策略：保持旧路由可用，新路由通过子模块或新版本前缀引入

测试与调试

• 本地调试：开启 DOU_DEBUG 后可获得更详细的异常信息
• 工具建议：使用 Postman/Curl 构造请求，设置 Authorization 头与必要的请求体
• 常见问题：
  • 401：检查 token 是否有效、是否过期
  • 403：检查鉴权模式与 work_required 策略
  • 404：检查 route 参数与模块/动作是否存在
  • 429：检查限流规则与重试间隔