Skip to content

API参考文档

Jump to bottom
Luca edited this page Aug 26, 2026 · 2 revisions

API参考文档

**本文引用的文件** - [apps/server/openapi.yaml](https://github.com/voidvec/fulla/blob/master/apps/server/openapi.yaml) - [docs/backend/api-reference.md](https://github.com/voidvec/fulla/blob/master/docs/domains/api-reference.md) - [libs/drogon/include/fulla/drogon/controllers/AuthorizationEndpointController.h](https://github.com/voidvec/fulla/blob/master/libs/drogon/include/fulla/drogon/controllers/AuthorizationEndpointController.h) - [libs/drogon/include/fulla/drogon/controllers/TokenEndpointController.h](https://github.com/voidvec/fulla/blob/master/libs/drogon/include/fulla/drogon/controllers/TokenEndpointController.h) - [libs/drogon/include/fulla/drogon/controllers/DiscoveryController.h](https://github.com/voidvec/fulla/blob/master/libs/drogon/include/fulla/drogon/controllers/DiscoveryController.h) - [apps/server/src/bootstrap/ControllerRegistration.cc](https://github.com/voidvec/fulla/blob/master/apps/server/src/bootstrap/ControllerRegistration.cc) - [apps/server/src/bootstrap/OpenApiSetup.cc](https://github.com/voidvec/fulla/blob/master/apps/server/src/bootstrap/OpenApiSetup.cc) - [docs/backend/security-hardening.md](https://github.com/voidvec/fulla/blob/master/docs/architecture/security-architecture.md)

目录

  1. 简介
  2. 项目结构
  3. 核心组件
  4. 架构总览
  5. 详细组件分析
  6. 依赖关系分析
  7. 性能与速率限制
  8. 故障排查指南
  9. 结论
  10. 附录

简介

本文件为 Fulla 的完整 API 参考，覆盖 OAuth2/OIDC、管理接口、用户自助服务、外部身份提供商集成等。内容基于仓库中的 OpenAPI 规范与控制器头文件整理，提供端点方法、URL 模式、请求/响应格式、认证方式、错误码与安全注意事项。版本信息来源于 OpenAPI 元数据；向后兼容性以 OpenAPI 变更为准。

项目结构

Fulla 后端采用 Drogon 框架，通过显式注册控制器暴露 HTTP 端点，OpenAPI 规范在启动时生成并输出到 docs/api/openapi.json，同时提供 Swagger UI 浏览。关键入口包括：

  • 控制器注册：集中注册所有控制器（OAuth2、OIDC、Admin、User Self-Service、MFA、WebAuthn、组织管理等）
  • OpenAPI 设置：根据监听器配置生成 server URL 并写入 openapi.json
  • 安全与限流：全局安全头注入与 Hodor 插件速率限制
graph TB
Client["客户端"] --> Router["Drogon 路由"]
Router --> CtrlReg["控制器注册<br/>ControllerRegistration.cc"]
CtrlReg --> AuthCtrl["授权端点控制器<br/>AuthorizationEndpointController.h"]
CtrlReg --> TokenCtrl["令牌端点控制器<br/>TokenEndpointController.h"]
CtrlReg --> DiscCtrl["发现端点控制器<br/>DiscoveryController.h"]
CtrlReg --> AdminCtrl["管理控制器(示例: Client/User/Role/Scope)"]
CtrlReg --> UserCtrl["用户自助服务控制器"]
CtrlReg --> MfaCtrl["MFA 控制器"]
CtrlReg --> OrgCtrl["组织控制器"]
OpenApi["OpenAPI 生成<br/>OpenApiSetup.cc"] --> Docs["openapi.json / Swagger UI"]
Loading

图表来源

章节来源

核心组件

  • OAuth2/OIDC 协议端点：授权、令牌、用户信息、发现、JWKS、设备授权、令牌撤销与探测
  • 管理 API：客户端、用户、角色、权限范围、令牌、审计日志、仪表盘统计
  • 用户自助服务：个人资料、密码修改、已授权应用、邮箱验证、密码重置、WebAuthn
  • 外部身份提供商：Google、GitHub、微信（可选编译开关）
  • 系统健康检查与健康探针

章节来源

架构总览

下图展示典型授权码流程中各端点的调用顺序与交互主体。

sequenceDiagram
participant C as "客户端"
participant A as "授权端点 /oauth2/authorize"
participant L as "登录/会话"
participant T as "令牌端点 /oauth2/token"
participant U as "用户信息 /oauth2/userinfo"
C->>A : GET ?response_type=code&client_id&redirect_uri&scope&state
A-->>C : 302 重定向至登录或同意页
C->>L : 提交用户名/密码或完成MFA
L-->>A : 返回授权码(code)
C->>T : POST grant_type=authorization_code&code&redirect_uri&client_id&client_secret
T-->>C : {access_token, token_type, expires_in, refresh_token}
C->>U : GET Authorization : Bearer {access_token}
U-->>C : 200 用户信息(JSON)
Loading

图表来源

详细组件分析

OAuth2/OIDC 协议端点

章节来源

管理 API

  • 客户端管理

    • /api/admin/clients: GET/POST
    • /api/admin/clients/{clientId}: GET/PUT/DELETE
    • /api/admin/clients/{clientId}/reset-secret: POST
    • /api/admin/clients/{clientId}/scopes: GET/PUT
    • 认证: Bearer Token
    • 参考路径: apps/server/openapi.yaml:72-241

  • 用户管理

    • /api/admin/users: GET
    • /api/admin/users/{userId}: GET/PUT
    • /api/admin/users/{userId}/disable: PUT
    • /api/admin/users/{userId}/enable: POST
    • /api/admin/users/{userId}/roles: GET/PUT
    • 认证: Bearer Token
    • 参考路径: apps/server/openapi.yaml:345-561

  • 角色与权限范围

    • /api/admin/roles: GET/POST
    • /api/admin/roles/{roleId}: PUT/DELETE
    • /api/admin/scopes: GET/POST
    • /api/admin/scopes/{scopeId}: PUT/DELETE
    • 认证: Bearer Token
    • 参考路径: apps/server/openapi.yaml:562-808

  • 令牌与审计

    • /api/admin/tokens: GET
    • /api/admin/tokens/{tokenPrefix}: DELETE
    • /api/admin/tokens/revoke-by-client: POST
    • /api/admin/tokens/revoke-by-user: POST
    • /api/admin/logs: GET
    • 认证: Bearer Token
    • 参考路径: apps/server/openapi.yaml:242-344

  • 仪表盘统计

章节来源

用户自助服务与辅助接口

章节来源

认证方法与鉴权

  • Bearer Token: 用于受保护的管理与用户自助接口
  • 客户端凭据: Basic 或表单参数（client_id/client_secret），用于 /oauth2/token、/oauth2/introspect、/oauth2/revoke
  • 过滤器: OAuth2AuthFilter 对 /oauth2/userinfo 等端点进行访问令牌校验
  • 参考路径: apps/server/openapi.yaml:27-35, TokenEndpointController.h:33-63

章节来源

错误码定义

  • 应用错误码: 统一 Error Envelope，包含 category/code/details/message/request_id
  • OAuth2 协议错误码: RFC 6749 §5.2 标准 error/error_description/error_uri
  • HTTP 状态码映射: 400/401/403/429/500/503 等
  • 参考路径: docs/backend/api-reference.md:213-281

章节来源

WebSocket 与实时通信

  • 当前仓库未提供 WebSocket 相关控制器或路由定义。如需实时通信，建议在后端引入 WebSocket 控制器并在 ControllerRegistration 中注册。

[本节不直接分析具体代码文件]

依赖关系分析

  • 控制器注册依赖：所有控制器通过显式 registerController 注册，确保路由与 OpenAPI 文档一致
  • 插件依赖：OAuth2Plugin 注入到各控制器与过滤器，提供统一的认证、限流、审计能力
  • OpenAPI 生成：启动时读取监听器配置生成 server URL，并输出 openapi.json
graph LR
Reg["ControllerRegistration.cc"] --> AuthCtrl["AuthorizationEndpointController.h"]
Reg --> TokenCtrl["TokenEndpointController.h"]
Reg --> DiscCtrl["DiscoveryController.h"]
Plugin["OAuth2Plugin"] --> AuthCtrl
Plugin --> TokenCtrl
Plugin --> DiscCtrl
OpenApi["OpenApiSetup.cc"] --> Spec["openapi.json"]
Loading

图表来源

章节来源

性能与速率限制

  • 速率限制：使用 Hodor 插件实现令牌桶算法，支持 IP/用户/全局多层级限制，白名单跳过限制
  • 关键接口限制示例：/oauth2/login、/oauth2/token、/api/register 有严格每分钟限制，超限返回 429
  • 安全响应头：全局注入现代安全头，防御常见 Web 攻击
  • 参考路径: docs/backend/security-hardening.md:5-32

章节来源

故障排查指南

  • 无法访问 Swagger UI：确认静态资源目录存在且服务已启用
  • OpenAPI 生成失败：运行单元测试定位注册错误，检查控制器是否已正确注册
  • 文档不一致：确保控制器变更后重新生成 openapi.json 并提交
  • 参考路径: docs/backend/api-reference.md:284-310

章节来源

结论

Fulla 提供了完整的 OAuth2/OIDC 协议端点与管理 API，遵循标准规范并通过 OpenAPI 进行契约化管理。结合 Hodor 速率限制与安全响应头，具备生产可用性与可观测性。建议按本参考文档进行集成与测试，关注错误码与限流策略，确保稳定运行。

[本节不直接分析具体代码文件]

附录

API 版本与向后兼容

  • 版本: 1.0.0（来自 OpenAPI info.version）
  • 向后兼容: 以 OpenAPI 变更为准；新增字段应向后兼容，删除或破坏性变更需评估影响

章节来源

调试与监控

章节来源

fulla wiki

Clone this wiki locally