读懂 ThunderID 后端源码:handler→service→store 分层与 Flow 执行引擎原理全解析
读懂 ThunderID 后端源码:handler→service→store 分层与 Flow 执行引擎原理全解析
ThunderID 是一个高性能的开源身份(Identity)技术栈,用一套 Go 后端统一管理人类、AI 代理和机器的访问权限。本文带你拆解它后端的 handler→service→store 三层架构,并深入讲解 Flow 执行引擎——驱动所有登录流程的核心——的运行原理,帮助新手快速读懂这份源码。
一、先建立全局认知:ThunderID 的控制面与数据面
在逐行读代码之前,先用 1 分钟建立全局观。ThunderID 是一个代码库、两种构建产物:
- 数据面(Data Plane):
backend/cmd/server,用户真正在这里登录、获取 Token,并运行 Flow 执行引擎; - 控制面(Control Plane):
backend/cmd/cpserver,负责编写和下发配置,把配置版本"捕获并应用"到它管理的各个数据面。
两种身份类型——用户、AI 代理、机器——在 ThunderID 中都是一等公民,用同一套目录、角色和 API 来管理:
整套平台的服务分布如下:控制面提供 Directory、Authz、Configuration、Deployment 等 API;数据面则内置 Gateway 管理、协议引擎(OAuth/SAML)和 Flow Orchestration Engine(Flow 编排引擎):
更完整的说明见仓库根目录的架构文档 ARCHITECTURE.md。
二、拆解 handler→service→store 分层:每个域模块的三层职责
ThunderID 后端有一个极其统一的设计约定:每个业务域(domain)包内部都是 handler → service → store 三层结构,并用单一的 Initialize(mux, …) 函数(位于各包的 init.go)向引擎注册路由。只要看懂一个模块,你就看懂了所有模块。
以 Flow 管理模块 backend/internal/flow/mgt/ 为例:
| 层 | 文件 | 职责 |
|---|---|---|
| Handler | handler.go | 解析 HTTP 请求、分页参数、URL 查询条件;把参数原样透传给 service,不做业务判断 |
| Service | service.go | 核心业务逻辑:定义 FlowMgtServiceInterface 接口,处理创建/更新时的图校验、共享(sharing)、审计事件等 |
| Store | store.go | 纯数据访问:定义 flowStoreInterface,操作 id、handle、flow_type、active_version 等数据库列,兼容 SQLite 与 Postgres |
// flowmgt 中的分层骨架(简化示意)
type flowMgtHandler struct {
service FlowMgtServiceInterface // handler 只依赖 service 接口
}
几个值得新手注意的细节:
- 接口注入 + Mock 测试:每一层都通过接口(如
FlowMgtServiceInterface)解耦依赖,测试文件中的*_mock_test.go就是为这些接口生成的 Mock,这使得单元测试无需真实数据库; - Handler 做输入消毒:如 flowexec/handler.go 中对每个入参调用
SanitizeString,防御注入攻击; - Store 面向双数据库:仓库的 backend/dbscripts/ 提供了 Postgres 与 SQLite 两套初始化脚本,Store 层因此成为唯一"感知"存储方言的地方。
用户管理模块 backend/internal/user/、应用管理 backend/internal/application/ 的结构与之完全一致,可对照 user/handler.go 与 user/service.go 自行验证。
三、Flow 执行引擎原理:把登录变成一张"可执行的节点图"
这是 ThunderID 最精彩的部分。传统 IAM 中,登录流程是硬编码的 if-else;而 ThunderID 把认证/注册流程定义成一张 JSON 节点图,由引擎按图逐步执行。
Flow 由以下节点类型组成,定义在 flow/common/constants.go#L20-L35:
| 节点类型 | 含义 |
|---|---|
START / END |
流程起止(表示型节点) |
PROMPT |
向用户展示界面(表单、按钮),等待输入 |
TASK_EXECUTION |
执行一个 executor(如验证凭据、发送 OTP) |
CALL |
调用另一个子流程 |
VARIABLES |
声明并解析流程变量 |
典型链路是:START → PROMPT → TASK → DECISION → COMPLETE。每个 TASK 节点指定一个 executor,比如 "CredentialsAuthExecutor"、"PasskeyExecutor"——内置 executor 每个一个文件,集中在 backend/internal/flow/executor/ 目录(凭据、Magic Link、Passkey、OAuth、OTP、Consent 等 30 余种)。
下面这张图就是一个真实的节点图实例:Sign In 表单提交后,走 Identifier + Password 任务节点验证凭据,再进入 User Consent(同意)节点,最后由 Auth Assertion Generator 生成断言到达 END:
引擎主循环:一次请求执行多少步?
引擎入口是 flowexec/engine.go#L81-L130 中的 flowEngine.Execute,每次 HTTP 请求进来,它执行以下循环:
- 定位当前节点
setCurrentExecutionNode——从持久化的流程上下文中恢复"上次执行到哪儿了"; - 运行 PRE 拦截器(如 captcha、challenge token),拦截器可提前终止流程;
for循环执行节点:调用executeNodePackage,节点自己决定"继续走下一个节点、暂停等待用户输入、还是结束";- 循环直到遇到终止条件:遇到
PROMPT需要用户输入就暂停,把FlowStep返回给客户端;客户端带着executionId再次POST /flow/execute,引擎从断点继续。
这意味着一个完整的登录可以是多轮 HTTP 请求,每一轮引擎都"接着上次的位置"执行——这就是 Flow 引擎"可编排"的本质。
状态从哪来?runtime_transient 存储
引擎本身无状态。每次执行结束前,当前节点、执行历史等上下文会序列化为 FlowContextDB,按 executionId 为键、带 TTL 地写入 runtime transient 存储(Redis 或数据库),见 flowexec/store.go。节点图本身则由 graphbuilder/graph_builder.go 构建,并带版本化缓存:流程定义更新(activeVersion 变化)时旧图自动失效重建。
Executor 如何注册?
所有 executor 通过 executor/init.go 的 Initialize 注册到 ExecutorRegistry,名称常量集中在 executor/constants.go。想给 ThunderID 加一种新认证方式(比如某种生物识别),只需三步:实现 core.ExecutorInterface → 在 constants.go 加名字 → 在注册逻辑中登记。
四、一次登录请求的完整旅程
把前两部分串起来,一次"应用原生模式"的登录是这样的:
Gate SPA → POST /flow/execute(携带 applicationId)
→ handler 解析请求、service 恢复 FlowContext
→ flowEngine 从断点执行节点图
→ 返回 FlowStep(PROMPT 等输入 / COMPLETE / REDIRECT)
→ 客户端循环调用直到 status: COMPLETE,换取 Token
而 OAuth 模式下,则是 GET /oauth2/authorize → 302 到 /gate → Gate SPA 循环调用 /flow/execute → 302 回跳携带 code → POST /oauth2/token。两种模式的差异仅在于谁驱动 /flow/execute 这个循环。
五、上手路线图:按这个顺序读源码
🧭 建议的新手阅读路线(全部为相对仓库根目录的路径):
- 架构总览:ARCHITECTURE.md → 引擎装配 backend/pkg/thunderidengine/engine.go
- 分层三件套:任选一个域,如 flow/mgt/handler.go → service.go → store.go
- Flow 核心模型:flow/core/node.go(节点接口)→ flow/common/constants.go(节点类型)
- 执行引擎:flow/flowexec/engine.go → flow/flowexec/handler.go(
/flow/execute入口) - Executor 全家桶:flow/executor/,从
credentials_auth_executor.go读起
✅ 小结:ThunderID 后端 = 一套严格的 handler→service→store 分层 + 一张用 JSON 描述、由 Flow 引擎逐步驱动的身份流程图。分层让每个业务域独立可测,Flow 引擎让"登录"从硬编码变成了可配置、可插拔的图——读懂这两点,你就拿到了这份代码库的钥匙。



