API接口设计 | DouPHP 开发手册 | 文档中心 | DouPHP企业建站系统

API接口设计

简介

本技术文档面向DouPHP小程序API端，系统化说明RESTful接口设计规范、请求与响应数据格式、认证授权机制、错误处理策略以及最佳实践。文档基于代码仓库中的API入口、路由解析、中间件、鉴权门面与错误码定义进行梳理，帮助开发者在小程序端正确对接并稳定调用后端接口。

项目结构

API端采用“入口统一、声明式路由、分层中间件、控制器返回标准JSON”的架构：

入口：api/index.php 负责初始化、异常兜底与响应发送。
路由：通过 api/foundation/routing/Router.php 与 ApiResolver.php 将 ?route=module/action 映射到控制器方法，并组装中间件栈。
中间件：安全头、代理信任、限流、用户认证等按模块粒度配置（api/init/middleware.php）。
鉴权：UserAuthMiddleware 从 Authorization: Bearer <token> 提取令牌，交由 api/facade/Auth.php 解析上下文并注入当前用户与工作端身份。
响应：统一使用 ApiResponse 标准包络；错误码集中定义于 core/foundation/Api/ApiCodes.php。

graph TB
Client["客户端<br/>小程序"] --> Entry["API入口<br/>api/index.php"]
Entry --> Router["路由调度器<br/>api/foundation/routing/Router.php"]
Router --> Resolver["API解析器<br/>api/foundation/routing/ApiResolver.php"]
Resolver --> MW["中间件栈<br/>Security/TrustProxy/Throttle/UserAuth"]
MW --> Controller["业务控制器<br/>api/controller/*"]
Controller --> Service["服务层/模型"]
Controller --> Resp["统一响应<br/>ApiResponse + ApiCodes"]

图表来源

api/index.php:27-55
api/foundation/routing/Router.php:43-67
api/foundation/routing/ApiResolver.php:60-90
api/middleware/UserAuthMiddleware.php:47-64
core/foundation/Api/ApiCodes.php:28-75

章节来源

api/index.php:27-55
api/foundation/routing/Router.php:28-67
api/foundation/routing/ApiResolver.php:30-90
api/init/middleware.php:18-146

核心组件

API入口与异常处理：统一捕获未处理异常，生产环境返回标准500 JSON，开发环境可输出调试信息。
路由与分发：?route=module/action 形态进入，由 BackendDeclaredMatcher 匹配后产出 DispatchPlan，再经 Dispatcher 执行中间件管道与控制器。
中间件体系：默认包含安全头、代理信任、限流；当 features.user 开启时加入 user_auth 中间件。
认证授权：UserAuthMiddleware 从请求头读取 Bearer Token，调用 Auth::resolveUserContext 解析用户与工作端身份，并通过 hydrate 注入到后续控制器。
统一响应与错误码：所有接口返回 ApiResponse 标准包络，错误码使用 ApiCodes 常量，保证前后端契约一致。

章节来源

api/index.php:33-55
api/foundation/routing/ApiResolver.php:60-90
api/middleware/UserAuthMiddleware.php:25-64
core/foundation/Api/ApiCodes.php:28-75

架构总览

下图展示一次受保护接口的完整调用链路：客户端携带Token访问 -> 入口初始化 -> 路由匹配 -> 中间件校验 -> 控制器执行业务 -> 返回标准JSON。

sequenceDiagram
participant C as "客户端"
participant E as "API入口<br/>api/index.php"
participant R as "路由调度器<br/>Router.php"
participant A as "API解析器<br/>ApiResolver.php"
participant M as "中间件栈<br/>UserAuthMiddleware"
participant G as "鉴权门面<br/>Auth.php"
participant Ctrl as "控制器"
participant S as "服务/模型"
C->>E : HTTP 请求 (Authorization : Bearer <token>)
E->>R : dispatch()
R->>A : resolve(request, container)
A-->>R : DispatchPlan(含中间件)
R->>M : 执行中间件管道
M->>G : resolveUserContext(bearerToken)
G-->>M : {ok, userId, userProfile, work, workId}
M->>Ctrl : 注入身份后继续
Ctrl->>S : 执行业务逻辑
S-->>Ctrl : 结果数据
Ctrl-->>C : ApiResponse.success/error

图表来源

api/index.php:27-55
api/foundation/routing/Router.php:43-67
api/foundation/routing/ApiResolver.php:60-90
api/middleware/UserAuthMiddleware.php:47-64
api/facade/Auth.php:197-255

详细组件分析

认证与授权机制

令牌来源：客户端在请求头中携带 Authorization: Bearer <token>。
解析流程：UserAuthMiddleware 从 Request 获取 bearerToken，调用 Auth::resolveUserContext 解析用户与工作端身份，再通过 hydrate 注入到后续控制器。
模式控制：api/init/middleware.php 以 module / module/sub / module/sub/action 维度配置 public / optional / required 三种鉴权模式；work_required 子策略用于工作端权限校验。
未登录/无权限：中间件直接返回 401/403 标准JSON，避免进入控制器。

flowchart TD
Start(["进入中间件"]) --> ReadToken["读取 Authorization: Bearer <token>"]
ReadToken --> Resolve["Auth::resolveUserContext(token)"]
Resolve --> Check{"解析成功?"}
Check -- 否 --> Reject401["返回 401 UNAUTHORIZED"]
Check -- 是 --> Inject["hydrate(context) 注入用户与工作端身份"]
Inject --> WorkCheck{"是否要求工作端身份?"}
WorkCheck -- 是且缺失 --> Reject403["返回 403 FORBIDDEN"]
WorkCheck -- 否或满足 --> Next["放行至控制器"]

图表来源

api/middleware/UserAuthMiddleware.php:47-92
api/facade/Auth.php:197-255
api/init/middleware.php:18-146

章节来源

api/middleware/UserAuthMiddleware.php:25-92
api/facade/Auth.php:27-255
api/init/middleware.php:18-146

RESTful URL与HTTP方法约定

URL形态：api/index.php?route=module[/sub][/action]，路径数字段即id（例如 user/index/{id}）。
方法映射：路由声明文件中以 get/post 等方法注册动作，控制器方法名与路由 action 对应。
命名空间：模块级分组统一前缀，子控制器通过 sub 区分（如 user/weixin）。

示例参考：

用户模块路由声明见 api/route/user.php，包含登录、注册、资料编辑、微信相关等动作。

章节来源

api/index.php:29-31
api/foundation/routing/ApiResolver.php:60-90
api/route/user.php:35-70

请求与响应数据格式

请求体：优先使用 JSON 格式，字段类型与验证规则由控制器或服务层校验；非法参数返回 INVALID_PARAMS 或 VALIDATION_FAILED。
响应包络：统一 ApiResponse 标准结构，包含 code、message、data、errors、request_id 等字段；成功使用 success，失败使用 error。
辅助函数：json() 提供裸JSON响应（非标准包络），仅用于后台片段等非标准场景；API端应优先使用 ApiResponse。

章节来源

core/web/http/helpers.php:63-95
core/foundation/Api/ApiCodes.php:28-75

错误处理策略

入口兜底：api/index.php 捕获 DomainException 与通用 Exception/Throwable，生产环境返回 SERVER_ERROR 500 JSON，开发环境可输出调试信息。
业务异常：控制器抛出 DomainException 时，统一转换为 422 并附带 errors。
中间件拒绝：未登录返回 UNAUTHORIZED 401，无工作端身份返回 FORBIDDEN 403。
路由错误：未匹配返回 NOT_FOUND 404，方法不被接受返回 Method Not Allowed 405。

章节来源

api/index.php:33-55
api/foundation/routing/Router.php:49-60
api/middleware/UserAuthMiddleware.php:77-92

控制器基类与视图聚合

BaseController 为API控制器基类，继承核心BaseController并承载API端专属逻辑（如会员中心导航构建）。
服务调用统一通过 helper/门面（DB、auth('api')、language、route等），保持控制器简洁。

章节来源

api/controller/BaseController.php:24-61

依赖关系分析

入口依赖：Route、ApiResponse、异常处理器。
路由依赖：BackendDeclaredMatcher、Dispatcher、MethodResolver、MiddlewareRegistry。
中间件依赖：SecurityHeadersMiddleware、TrustProxyMiddleware、ThrottleMiddleware、UserAuthMiddleware。
鉴权依赖：Auth门面、ApiTokenService、UserService。
配置依赖：features.user、param.login_phone 等开关影响鉴权与行为。

graph LR
Entry["api/index.php"] --> Router["Router.php"]
Router --> Resolver["ApiResolver.php"]
Resolver --> MW["UserAuthMiddleware.php"]
MW --> AuthFacade["Auth.php"]
AuthFacade --> Config["config/config.php"]
Controller["控制器"] --> Codes["ApiCodes.php"]
Controller --> Resp["ApiResponse"]

图表来源

api/index.php:27-55
api/foundation/routing/Router.php:43-67
api/foundation/routing/ApiResolver.php:60-90
api/middleware/UserAuthMiddleware.php:47-64
api/facade/Auth.php:197-255
core/foundation/Api/ApiCodes.php:28-75

章节来源

api/index.php:27-55
api/foundation/routing/ApiResolver.php:60-90
api/facade/Auth.php:197-255
core/foundation/Api/ApiCodes.php:28-75

性能与并发建议

限流：ThrottleMiddleware 已集成，建议在高频接口（如登录、验证码）启用更严格的限流策略。
超时：客户端侧设置合理超时（建议3-5秒），服务端根据接口复杂度调整数据库查询与外部调用超时。
重试：对幂等GET请求可采用指数退避重试；写操作（POST/PUT/DELETE）需结合唯一键与去重表防止重复提交。
缓存：热点数据（商品列表、分类、配置）可使用缓存层降低数据库压力。
连接池：确保数据库连接池与队列任务池配置合理，避免高并发下资源耗尽。

故障排查指南

401 未登录：检查 Authorization: Bearer <token> 是否正确传递；确认接口在 auth_modes 中是否为 required。
403 无权限：确认用户具备工作端身份（work_required 子策略）；检查 features.user 是否开启。
404 未找到：核对 route=module/action 是否声明；确认资源ID是否存在。
422 参数错误：检查请求体字段类型与必填项；查看 errors 数组定位具体字段。
500 服务器错误：查看日志与 SiteDebugExceptionRenderer 输出；确认异常是否被入口兜底。

章节来源

api/middleware/UserAuthMiddleware.php:77-92
api/init/middleware.php:18-146
api/index.php:33-55

结论

DouPHP小程序API端通过统一的入口、声明式路由、分层中间件与标准响应包络，实现了清晰的RESTful接口设计与稳定的认证授权机制。开发者应遵循URL与方法约定、使用标准JSON格式、依据ApiCodes处理错误，并结合限流、超时与重试策略提升接口稳定性与用户体验。

附录：RESTful规范与调用示例

URL命名约定

基础路径：api/index.php?route=module[/sub][/action]
资源标识：路径中的数字段作为id（例如 user/index/{id}）
子控制器：通过 sub 区分功能域（如 user/weixin、user/work）

章节来源

api/index.php:29-31
api/route/user.php:35-70

HTTP方法使用

GET：查询资源（如 user/index、product/list）
POST：创建或提交数据（如 user/login_post、order/create）
PUT/PATCH：更新资源（视控制器实现）
DELETE：删除资源（视控制器实现）

章节来源

api/route/user.php:35-70

状态码与业务码

HTTP状态码：200成功、400参数错误、401未登录、403无权限、404未找到、422业务规则违反、500服务器错误。
业务码：使用 ApiCodes 常量（OK、INVALID_PARAMS、UNAUTHORIZED、FORBIDDEN、NOT_FOUND、BUSINESS_RULE_VIOLATION、SERVER_ERROR等）。

章节来源

core/foundation/Api/ApiCodes.php:28-75

请求与响应格式

请求头：Content-Type: application/json；Authorization: Bearer <token>（受保护接口）
响应体：{code, message, data, errors, request_id}
字段验证：控制器或服务层校验，错误时返回 VALIDATION_FAILED 并附带 errors

章节来源

core/web/http/helpers.php:63-95
core/foundation/Api/ApiCodes.php:28-75

认证授权流程

登录：调用 user/login_post 获取 token
鉴权：后续请求携带 Authorization: Bearer <token>
工作端：work_required 子策略要求工作端身份

章节来源

api/init/middleware.php:18-146
api/middleware/UserAuthMiddleware.php:47-92
api/facade/Auth.php:197-255

调用最佳实践

重试：对幂等GET请求采用指数退避重试；写操作需去重。
超时：客户端设置3-5秒超时；服务端优化慢查询。
并发：合理使用缓存与连接池；对高频接口启用限流。
日志：记录关键请求与错误，便于问题定位。

添加日期：2026-10-05