-
Notifications
You must be signed in to change notification settings - Fork 3
开发指南
vilas edited this page Aug 25, 2026
·
1 revision
**本文引用的文件**
- [CMakeLists.txt](https://github.com/voidvec/fulla/blob/master/CMakeLists.txt)
- [conanfile.py](https://github.com/voidvec/fulla/blob/master/conanfile.py)
- [README.md](https://github.com/voidvec/fulla/blob/master/README.md)
- [CONTRIBUTING.md](https://github.com/voidvec/fulla/blob/master/CONTRIBUTING.md)
- [CMakePresets.json](https://github.com/voidvec/fulla/blob/master/CMakePresets.json)
- [scripts/backend/build.sh](https://github.com/voidvec/fulla/blob/master/scripts/backend/build.sh)
- [scripts/backend/test.sh](https://github.com/voidvec/fulla/blob/master/scripts/backend/test.sh)
- [cmake/Warnings.cmake](https://github.com/voidvec/fulla/blob/master/cmake/Warnings.cmake)
- [cmake/Sanitizers.cmake](https://github.com/voidvec/fulla/blob/master/cmake/Sanitizers.cmake)
- [.clang-format](https://github.com/voidvec/fulla/blob/master/.clang-format)
- [paths.env](https://github.com/voidvec/fulla/blob/master/paths.env)
- [scripts/backend/env_common.sh](https://github.com/voidvec/fulla/blob/master/scripts/backend/env_common.sh)
- [scripts/backend/env_setup.bat](https://github.com/voidvec/fulla/blob/master/scripts/backend/env_setup.bat)
- [.github/workflows/ci.yml](https://github.com/voidvec/fulla/blob/master/.github/workflows/ci.yml)
Loading
Loading
Loading
Loading
Loading
- 简介
- 项目结构
- 核心组件
- 架构总览
- 详细组件分析
- 依赖分析
- 性能与构建优化
- 调试与工具链
- 编码规范与代码审查
- Git工作流与提交规范
- 新功能开发指南与最佳实践
- 测试驱动开发与持续集成
- 常见问题与故障排除
- 结论
本指南面向贡献者，提供Fulla的完整开发环境搭建、构建系统使用、编码规范、Git工作流、调试技巧、新功能开发指导、测试与CI配置以及常见问题排查。项目基于C++17、Drogon框架，采用CMake + Conan进行依赖与构建管理，支持Linux/macOS/Windows三平台，并提供完整的后端、前端与管理控制台。
仓库采用分层模块化组织：
- apps/server：授权服务器后端（Drogon C++）
- libs：SDK库包（common/oauth2/identity/storage-*/drogon）
- frontends/admin、frontends/user：管理端与用户端前端
- examples：SDK消费者示例
- deploy：Docker Compose、Helm、Nginx、可观测性
- tests：后端测试套件（单元/集成/契约/e2e/安全/性能）
- scripts：构建、测试与运维脚本
- docs：项目文档
graph TB
A["apps/server<br/>授权服务器"] --> B["libs/drogon<br/>插件/控制器/过滤器/视图"]
B --> C["libs/oauth2<br/>OAuth2/OIDC引擎"]
B --> D["libs/identity<br/>身份/MFA/WebAuthn/RBAC"]
B --> E["libs/storage-postgres<br/>ORM模型"]
B --> F["libs/storage-memory<br/>内存存储"]
B --> G["libs/storage-redis<br/>Redis存储"]
C --> H["libs/common<br/>共享内核/端口"]
D --> H
E --> D
F --> C
G --> C
图表来源
章节来源
- 构建系统与预设：通过CMakePresets统一多平台构建入口，配合Conan生成toolchain与依赖。
- 依赖管理：conanfile.py集中声明第三方依赖与可选特性开关，映射到CMake变量。
- 警告与错误策略：Warnings.cmake为第一方目标提升警告级别，并支持将警告视为错误。
- 检测器：Sanitizers.cmake提供TSan/ASan开关，仅GCC/Clang生效，建议Debug构建。
- 路径与环境：paths.env作为单一真实源，被脚本与CMake引用；env_common.sh解析预设名与路径。
- 测试与运行：build.sh与test.sh封装Conan安装、CMake配置与ctest执行流程。
章节来源
- CMakePresets.json:1-234
- conanfile.py:1-83
- cmake/Warnings.cmake:1-63
- cmake/Sanitizers.cmake:1-88
- paths.env:1-75
- scripts/backend/build.sh:1-168
- scripts/backend/test.sh:1-87
- scripts/backend/env_common.sh:1-83
后端按领域层与适配层解耦，领域层不依赖Drogon，由CI中的arch-guard强制校验。SDK可通过find_package消费，支持最小化依赖面。
sequenceDiagram
participant Dev as "开发者"
participant Conan as "Conan"
participant CMake as "CMake"
participant Build as "构建产物"
participant Test as "CTest"
Dev->>Conan : conan install (生成toolchain与deps)
Conan-->>Dev : 写入build/<preset>/conan_toolchain.cmake
Dev->>CMake : cmake --preset <preset>
CMake->>Build : 编译各模块(libs/apps/tests)
Build-->>Test : 生成fulla-tests等
Dev->>Test : ctest --output-on-failure
Test-->>Dev : 测试结果
图表来源
- CMakePresets.json:18-177
- conanfile.py:70-83
- scripts/backend/build.sh:119-156
- scripts/backend/test.sh:41-81
章节来源
- 顶层CMakeLists启用C++17、测试、可选功能开关（WITH_IDENTITY/WITH_SOCIAL/WITH_WEBAUTHN），并按顺序添加子目录以建立依赖方向。
- CMakePresets定义多平台/多配置预设（Release/Debug/ASAN/TSAN），并通过conan-base继承共享设置。
- conanfile.py声明依赖版本与选项，并在generate阶段将with_映射为CMake缓存变量WITH_。
flowchart TD
Start(["开始"]) --> ConanInstall["conan install . --output-folder=build/<preset>"]
ConanInstall --> Toolchain["生成conan_toolchain.cmake"]
Toolchain --> CMakeConfigure["cmake --preset <preset>"]
CMakeConfigure --> BuildTargets["编译所有目标(libs/apps/tests)"]
BuildTargets --> RunTests["ctest --output-on-failure"]
RunTests --> End(["结束"])
图表来源
- CMakeLists.txt:1-31
- CMakeLists.txt:57-120
- CMakePresets.json:18-177
- conanfile.py:70-83
- scripts/backend/build.sh:119-156
章节来源
- 依赖：Drogon、OpenSSL、jsoncpp、hiredis、libcurl、brotli、zlib、gtest（测试）。
- 可选特性：with_identity/with_social/with_webauthn，默认开启，关闭可缩小依赖面。
- 生成阶段：将Conan选项映射为CMake变量WITH_*，供顶层CMake option()消费。
章节来源
- 对第一方目标应用-Wall -Wextra（MSVC /W4），屏蔽第三方头噪音。
- 可通过FULLA_WERROR将警告视为错误，CI中开启。
章节来源
- 支持thread/address两种模式，仅GCC/Clang有效，建议Debug构建。
- 通过FULLA_SANITIZER缓存变量选择，函数oauth2_apply_sanitizer为目标追加编译与链接选项。
章节来源
- paths.env集中定义源码、构建输出、SQL/配置路径，被脚本与CMake引用。
- env_common.sh解析预设名、导出绝对路径，便于跨平台脚本一致性。
- Windows环境检查Conan/CMake可用性。
章节来源
- build.sh：安装依赖、配置CMake、构建、复制配置文件。
- test.sh：按预设运行ctest，支持标准与CI两套配置。
章节来源
- 依赖方向严格：Domain层（common/oauth2/identity）不依赖Drogon；storage-*实现适配器；drogon层聚合插件/控制器/视图。
- CI通过arch-guard静态检查确保分层约束。
graph LR
common["libs/common"] --> oauth2["libs/oauth2"]
common --> identity["libs/identity"]
oauth2 --> storage_memory["libs/storage-memory"]
oauth2 --> storage_redis["libs/storage-redis"]
identity --> storage_postgres["libs/storage-postgres"]
drogon["libs/drogon"] --> oauth2
drogon --> identity
drogon --> storage_memory
drogon --> storage_redis
drogon --> storage_postgres
图表来源
章节来源
- 使用CMake预设隔离不同平台/配置的构建目录，避免污染。
- 在CI中开启FULLA_WERROR保证零警告基线。
- 使用Sanitizers在Debug模式下定位内存与线程问题。
- 按需关闭可选特性（with_social/with_webauthn）减少依赖与编译时间。
[本节为通用指导，无需特定文件来源]
- 编译器要求：C++17（MSVC 2019+/GCC 9+/Clang 10+）。
- 构建工具：CMake 3.21+，Conan 2.x。
- 格式化：.clang-format统一风格（缩进、换行、括号位置等）。
- 调试：使用Debug预设或-sanitizer预设；VS/CLion等IDE可通过CMake导入工程。
- 日志：遵循六档日志级别，域层通过ILogger端口记录，便于测试断言。
章节来源
- 异步风格：回调函数最后一个参数为std::function<void(result)> &&；捕获时使用auto self = shared_from_this()，禁止CoroMapper。
- ORM模型：由drogon_ctl生成，禁止手工编辑；通过脚本重新生成。
- 数据库访问：优先使用异步Mapper + Criteria；原始SQL仅限DDL、UPDATE...RETURNING与批处理。
- 错误码：稳定字符串代码，注册于ErrorCatalog。
- 架构约束：Domain层不得包含Drogon头；CI通过tools/arch-guard强制执行。
- 无Emoji：代码与程序输出不使用Emoji，使用符号标记。
- 代码审查：PR必须通过CI全部门禁；公共SDK头变更需更新api-baseline。
章节来源
- 分支命名：feat/、fix/、docs/。
- 提交信息：遵循Conventional Commits（feat/fix/docs/test/build/ci/refactor）。
- 目标分支：master；所有PR必须通过CI后方可合并。
章节来源
- 新增领域能力时，优先放入libs/*（如oauth2/identity），保持与Drogon解耦。
- 若涉及存储适配，新建libs/storage-*并实现相应接口。
- 通过CMake option与conanfile.py的with_*开关控制可选功能的编译范围。
- 新增API需同步更新OpenAPI与测试用例，确保CI的api-diff门禁通过。
- 日志与可观测性：域层通过ILogger记录，基础设施层可使用LOG_*。
章节来源
- 本地测试：使用scripts/backend/test.sh运行ctest，支持标准与CI配置两套运行。
- 分类测试：通过标签Unit/Integration/E2E/Security/Performance筛选。
- CI门禁：
- 静态检查：arch-guard、migration-check、api-diff、OpenAPI校验。
- 构建与测试：Linux（GCC+DB）、Windows（MSVC内存存储）、macOS（Clang ARM64）。
- SDK烟测：examples/full-stack-host通过find_package消费。
- 前端属性测试：Vitest。
- 安全检查：敏感信息与依赖EOL检查。
sequenceDiagram
participant PR as "Pull Request"
participant CI as "GitHub Actions"
participant Static as "静态检查"
participant Build as "构建与测试"
participant Smoke as "SDK烟测"
PR->>CI : 触发ci.yml
CI->>Static : arch-guard/migration/api-diff/OpenAPI
Static-->>CI : 通过/失败
CI->>Build : 多平台矩阵构建与ctest
Build-->>CI : 结果
CI->>Smoke : find_package全栈验证
Smoke-->>CI : 结果
CI-->>PR : 状态汇总
图表来源
章节来源
- Conan未找到：安装Conan并确保PATH正确；首次运行会初始化profile。
- CMake配置失败：确认已执行conan install并生成toolchain；清理CMakeUserPresets.json后重试。
- 预设解析失败：检查操作系统类型与构建类型是否匹配预设；必要时使用manage.sh自动解析。
- 测试失败：先运行标准配置，再切换至CI配置；查看ctest输出与日志。
- Sanitizer无效：仅在GCC/Clang Debug构建下生效；MSVC不支持TSan。
- 警告视为错误：CI中开启FULLA_WERROR，本地可按需开启以提前发现问题。
章节来源
- scripts/backend/build.sh:106-156
- scripts/backend/env_common.sh:40-74
- cmake/Sanitizers.cmake:50-87
- cmake/Warnings.cmake:23-63
Fulla提供了现代化的C++授权服务器与SDK，采用清晰的领域分层与严格的CI门禁。通过CMake + Conan的统一构建、完善的测试与可观测性、规范的编码与Git工作流，贡献者可高效地参与开发、测试与发布。建议在新功能开发中遵循领域解耦、可选特性开关、测试先行与CI门禁原则，确保代码质量与可维护性。
fulla wiki
- 开发指南
- 快速开始
- 附录
-
API参考文档
- API参考文档
- API参考文档 - OAuth2_OIDC协议端点
- API参考文档 - 错误处理与状态码
- 用户自服务API
- 管理API
- 前端应用
- 安全设计
-
扩展开发
- 扩展开发
- 扩展开发 - SDK集成
- 存储扩展
- 插件开发
- 认证扩展
- 数据库设计
- 架构设计
-
核心库模块
- 核心库模块
- Drogon适配器 (fulla__drogon)
- OAuth2引擎 (fulla__oauth2)
- 存储适配器
- 身份认证模块 (fulla__identity)
- 通用库 (fulla__common)
- 测试策略
- 监控与可观测性
-
运维手册
- 运维手册
- 运维手册 - 生产环境配置
- 升级与迁移
- 故障排查指南
- 数据维护
- 日常运维操作
- 部署指南
- 项目概览