架构 on 姚玉亮的网络日志

Go 与 Python 混部：gRPC 还是 HTTP？我的选型权衡

Fri, 03 Jul 2026 10:30:00 +0800

混部是常态

AI 应用里 Go 和 Python 混部太常见了：Go 写网关、并发调度、业务 API，Python 写模型推理、向量计算、文档解析。我在数据集管理服务里用 Go（Hertz）做接入和任务分发，用 eino + pond 跑高并发文档解析和向量化；在 alchemy-furnace 里是 Go（Gin + GORM）做网关，Python（FastAPI）做合成引擎。

两边怎么通信，是每次都要回答的问题。选项就三个：gRPC、HTTP/JSON、消息队列。MQ 用于异步解耦没有争议，争议集中在同步调用：gRPC 还是 HTTP。

两个项目我都做过，结论是按场景分。

内部高频链路，我选 gRPC

数据集管理服务里，Go 调度器要把文档分片发给 Python worker 池，单批上百个分片，每个分片还要回传结构化的解析结果（段落、表格、向量）。这种内部高频、强类型、对延迟敏感的场景，gRPC 的优势很明显：Protocol Buffers 契约明确，流式传输支持分片回传，连接多路复用省掉反复握手。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


service ParserService {
 rpc Parse(stream ParseChunk) returns (stream ParseResult);
}

message ParseChunk {
 string doc_id = 1;
 bytes content = 2;
 int32 chunk_index = 3;
}

message ParseResult {
 string doc_id = 1;
 int32 chunk_index = 2;
 repeated Paragraph paragraphs = 3;
 repeated Table tables = 4;
 repeated float embedding = 5;
}

Go 侧用 google.golang.org/grpc 起长连接，Python 侧用 grpcio 实现 Servicer。双向流让 worker 可以边解析边回传，不用等整批收完。

跨边界调用，我选 HTTP/JSON

alchemy-furnace 的 Go 网关调 Python 合成引擎，我用的是 HTTP。原因有三个：一是合成本身耗时长（要调多个 LLM 供应商），gRPC 的流式优势发挥不出来；二是开发期用 curl/Postman 直接调试 HTTP 方便太多；三是网关前面还有 Nginx，HTTP 路径的超时、重试、日志都更成熟。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


// alchemy-furnace 网关调用 Python 合成引擎
type FusionRequest struct {
 SkillIDs []string `json:"skill_ids"`
 Strategy string `json:"strategy"`
 Model string `json:"model"`
}

func (c *FusionClient) Fuse(ctx context.Context, req *FusionRequest) (*FusionResult, error) {
 body, _ := json.Marshal(req)
 httpReq, _ := http.NewRequestWithContext(ctx, "POST", c.baseURL+"/fuse", bytes.NewReader(body))
 httpReq.Header.Set("Content-Type", "application/json")
 resp, err := c.hc.Do(httpReq)
 if err != nil {
 return nil, err
 }
 defer resp.Body.Close()
 var out FusionResult
 if err := json.NewDecoder(resp.Body).Decode(&out); err != nil {
 return nil, err
 }
 return &out, nil
}

四笔账

第一笔，gRPC 的 Python 侧性能没那么神。有点反直觉，但 Python 受 GIL 限制，同步 Servicer 吞吐一般，要用 grpc.aio 异步实现 + 多进程 worker 才能打满。Go 调 Python 时，瓶颈往往在 Python 这边的 CPU，协议开销反而是小头。数据集管理服务里我们靠 pond 在 Go 侧控制并发度，再配合多个 Python 进程横向扩容。

第二笔，gRPC 的调试成本真实存在。链路追踪、错误码、payload 查看都比 HTTP 麻烦，KubeSphere 里抓包也不直观。我的做法是内部 gRPC 服务默认开 reflection，开发期用 grpcurl 调试；生产环境必须接 Jaeger，把每次调用的方法、状态、耗时打进 trace。

第三笔，版本兼容要守纪律。Protobuf 字段只能加，不能改类型，不能复用 tag，这条比 JSON 严格得多。我在 CI 里加了 buf breaking 检查，防止有人图省事改字段，老客户端解析错乱。

第四笔，流式场景 gRPC 优势确实明显。数据集管理服务里解析一个大文档要几十秒，用 HTTP 轮询或长连接收 JSON，连接管理和超时都很别扭；gRPC 双向流天然适合"请求一次、结果分批回"。

后来

我的选型原则：内部高并发 + 结构化 + 流式用 gRPC；跨边界、低频、强调试便利性用 HTTP。别为了"显得先进"在所有地方都上 gRPC，也别为了省事在高频内部链路上用 JSON 硬扛。协议是手段，把瓶颈和团队维护成本算清楚，答案自然就出来了。

封面图：thebarrowboy / Flickr · CC BY 2.0

Go 网关 + Python 合成引擎 + Next.js 三段式架构实践

Fri, 13 Feb 2026 10:30:00 +0800

全用一种语言，两头都不舒服

alchemy-furnace 立项时，我面对一个很典型的矛盾：我是 Go 主力，后端那一套（Gin、GORM、Wire、并发模型）写得最顺；但炼丹的核心，提示词变异算子、多供应商 LLM 适配、后面可能要接的 agent 编排，Python 生态明显更快。前端我又想用 Next.js 做一个交互流畅的控制台，不想套模板。

全用一种语言呢？要么牺牲迭代速度，让 Go 手搓 prompt 实验；要么牺牲工程稳定性，让 Python 扛业务网关和并发。两条路都不痛快，所以一开始我就定了三段式：Go 网关、Python 合成引擎、Next.js 前端。这篇讲它们怎么切、怎么连，踩了哪些坑。

稳定的归 Go，易变的归 Python

职责切分就一条原则：稳定的、要强类型和高并发的归 Go；易变的、AI 实验性强的归 Python；交互和渲染归 Next.js。

Go 网关（gateway）：用户认证、API Key 管理、金丹/任务/产物的 CRUD、计费配额、请求签名、SSE 进度推送、对 Python 引擎的调用与降级。Gin + GORM + Wire，MySQL 存元数据，Redis 做任务队列和缓存。
Python 合成引擎（furnace-engine）：融合算子（crossover/mutate/ensemble）、多供应商 LLM 适配层、提示词缓存、血统计算。FastAPI + httpx，无状态，水平扩展靠 K8s 加副本。
Next.js 前端（console）：金丹编辑器、炼丹任务向导、分身对话沙箱、血统图谱可视化。App Router + SSE 消费网关进度。

三段之间的调用链：

1
2
3


Browser ──HTTP/SSE──> Go Gateway ──HTTP+签名──> Python Engine
 │
 └──> MySQL / Redis / S3

Python 引擎不直接暴露给浏览器，也不直连业务库。它只接收网关签名过的任务请求，必要时从 S3 读写大对象。这样安全边界是清楚的：引擎挂了，用户登录和数据查询照常，网关还能返回降级结果。

网关到引擎：签名、超时、降级

Go 调 Python 这一层我封了一个 client，带超时、重试和签名。签名用 HMAC-SHA256，防的是引擎被内网其他服务误调：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28


type FurnaceClient struct {
 cli *http.Client
 baseURL string
 signSecret string
}

func (c *FurnaceClient) Submit(ctx context.Context, job FurnaceJob) (*FurnaceAck, error) {
 body, _ := json.Marshal(job)
 req, _ := http.NewRequestWithContext(ctx, "POST",
 c.baseURL+"/v1/furnace/fuse", bytes.NewReader(body))
 req.Header.Set("Content-Type", "application/json")
 ts := strconv.FormatInt(time.Now().Unix(), 10)
 req.Header.Set("X-Furnace-Ts", ts)
 req.Header.Set("X-Furnace-Sign",
 c.sign(body, ts)) // HMAC-SHA256(secret, ts+body)

 resp, err := c.cli.Do(req)
 if err != nil {
 return nil, fmt.Errorf("furnace call: %w", err)
 }
 defer resp.Body.Close()
 if resp.StatusCode >= 500 {
 return nil, ErrFurnaceUnavailable // 网关层触发降级
 }
 var ack FurnaceAck
 json.NewDecoder(resp.Body).Decode(&ack)
 return &ack, nil
}

Python 侧用一个轻量依赖校验签名：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


from fastapi import Request, HTTPException
import hmac, hashlib, time

async def verify_signature(request: Request):
 secret = settings.FURNACE_SIGN_SECRET
 ts = request.headers.get("X-Furnace-Ts", "")
 sign = request.headers.get("X-Furnace-Sign", "")
 body = await request.body()
 expected = hmac.new(
 secret.encode(),
 (ts.encode() + body),
 hashlib.sha256,
 ).hexdigest()
 if not hmac.compare_digest(expected, sign):
 raise HTTPException(status_code=401, detail="bad signature")
 if abs(time.time() - int(ts)) > 300:
 raise HTTPException(status_code=401, detail="stale timestamp")

前端的进度条走 SSE，网关把引擎的阶段事件透传成统一格式：

1
2
3
4
5
6
7


// Next.js 客户端
const evt = new EventSource(`/api/fusion/${jobId}/stream`);
evt.onmessage = (e) => {
 const { stage, message } = JSON.parse(e.data);
 setStages((s) => [...s, { stage, message }]);
 if (stage === "done" || stage === "failed") evt.close();
};

四个抉择

第一个抉择是同步还是异步。融合任务要调 LLM，耗时几秒到几十秒。我没让网关同步阻塞着等引擎，而是引擎返回 job_id，网关写任务表，引擎通过回调 + SSE 推进度。好处是网关不会被长连接拖垮，坏处是多了一套任务状态机。中间态放 Redis，终态进 MySQL，状态流转集中在 Go 侧，Python 只发事件、不直接改库。

第二个是缓存放哪。引擎要保持无状态，滚动更新和扩缩容才安全，所以合成提示词缓存（后面单篇讲）放在 Redis 里，实例本身不持有本地状态。代价是每次多一次网络往返，但跟一次 LLM 调用比，这点开销可以忽略。

第三个是 CORS 和 Cookie，这块坑过我。Next.js 开发时直连 Go 网关会跨域，我没有放开 CORS 让浏览器直连，而是在 Next.js 里用 Route Handler 做反向代理：同源访问，Cookie 和 SSE 都干净。生产上由 KubeSphere 的网关统一路由。

第四个是要不要上 gRPC。我考虑过，最后没上。引擎接口变化快、字段常加，HTTP+JSON 在这个阶段调试成本最低，pydantic 做校验也够用。等接口稳定、QPS 真上来了，再把内部高频调用换成 gRPC 不迟。我在某 SaaS 公司做过 fasthttp 到 go-zero 的迁移，过早引入复杂 RPC 的代价，我是见识过的。

后来

三段式不是为了炫技，就是让每种语言干它最擅长的事：Go 守住稳定和并发的底线，Python 承接 AI 的快速迭代，Next.js 提供交互体验。边界靠三条约束维持：Python 不直连业务库，所有内部调用带签名，任务状态归 Go 管。这套结构让我能一个人把全栈交付下来，任何一层也没有长成难维护的大泥球。

封面图：Me in ME / Flickr · CC BY 2.0

数据集管理服务架构设计

Sun, 08 Jun 2025 10:30:00 +0800

为什么不做成单体

某科技公司的 AI 数据平台需要一个统一的数据集管理服务：往上支撑学术文档上传、解析、向量化、知识图谱构建，往下给知识库问答服务供检索能力。数据形态从 PDF、Word 到图片、结构化表格都有，存储量大，处理链路又长又耗资源。

之所以不做成单体，是因为上传、解析、检索混在一个进程里会互相影响，任何一边都没法独立扩缩容。数据集管理服务就是照着这个约束设计的，后端架构由我主导。

整体怎么拆

服务基于 Hertz（字节开源的 HTTP 框架）搭，按职责拆成几块。API 层管数据集 CRUD、文档上传、检索接口，用 Hertz 的路由分组和中间件做鉴权、日志、限流。存储层分三份：原始文件放 S3 兼容对象存储（MinIO），元数据存 GaussDB，向量和图谱实体存 MongoDB，向量一个集合，图遍历也靠它。处理层用 eino 编排解析流水线，并发交给 pond，前两篇已经讲过。检索层做向量加关键词的混合召回，支持按数据集、文档、元数据过滤。

模块间的依赖注入用 Wire，Service/DAO/Client 各归各层：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


// wire.go
func NewDatasetService(
 cfg *Config,
 db *gorm.DB,
 mongo *mongo.Client,
 s3 *s3.Client,
 temporalClient client.Client,
 chain *eino.Chain,
) *DatasetService {
 // ...
}

上传直传，解析异步

上传走 S3 预签名，前端直传对象存储，不占用服务带宽：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


func (h *DatasetHandler) PresignUpload(c context.Context, ctx *app.RequestContext) {
 var req UploadReq
 if err := ctx.BindAndValidate(&req); err != nil {
 ctx.JSON(400, errResp(err))
 return
 }
 key := fmt.Sprintf("datasets/%s/%s%s", req.DatasetID, snowflake.NextID(), extOf(req.Filename))
 url, err := h.s3.PresignPutObject(c, key, 15*time.Minute)
 if err != nil {
 ctx.JSON(500, errResp(err))
 return
 }
 ctx.JSON(200, map[string]any{"url": url, "object_key": key})
}

前端拿到预签名 URL 直传 S3，传完回调服务，服务创建文档记录、投递解析任务。

处理链路交给 Temporal 编排（和数据治理服务共用一个 Temporal 集群），每个文档一个 workflow，内部调 eino Chain 走完解析、分块、embedding、写图谱。重试、超时、状态持久化都是 Temporal 的活，服务重启任务也不丢。

检索是多路召回

检索接口对知识库问答服务只暴露一个统一的 Search：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


type SearchService struct {
 vecStore VectorStore
 kwStore KeywordStore
 graph GraphStore
}

func (s *SearchService) Search(ctx context.Context, req *SearchReq) (*SearchResp, error) {
 // 1. 向量召回
 vecHits, err := s.vecStore.Search(ctx, req.DatasetID, req.QueryEmbedding, req.TopK)
 if err != nil {
 return nil, err
 }
 // 2. 关键词召回（BM25）
 kwHits, _ := s.kwStore.Search(ctx, req.DatasetID, req.Query, req.TopK)
 // 3. 融合排序（RRF）
 fused := rrfFuse(vecHits, kwHits)
 // 4. 图谱扩展：对 top 结果关联实体补充邻接信息
 enriched := s.graph.Expand(ctx, fused, req.DatasetID)
 return &SearchResp{Hits: enriched}, nil
}

五个关键取舍

上传和处理必须拆开。最初想在上传接口里同步解析，大文件一进来接口就超时。改成预签名直传加 Temporal 异步任务之后，接口只管元数据和任务投递，处理能力想扩就单独扩。文档状态用状态机管理（uploaded → parsing → parsed / failed），前端轮询或订阅进度。

存储选型上，GaussDB 存结构化元数据（数据集、文档、权限），MongoDB 存向量和非结构化 chunk，主要看中它的向量索引和文档模型，跟 chunk 加 metadata 的形态正合适。图谱没有引入独立图数据库，实体和关系就用 MongoDB 集合存，当前规模够用，还省掉一个中间件的运维成本；等图遍历深度真上去了，再换专门的图库不迟。

大文件和小文件分开对待。几百页的 PDF 解析起来很吃内存，我们在 Temporal workflow 里按页拆 activity，每页独立处理、独立落盘，避免整个文档一口气读进内存。小文件反过来，批量合并处理，省 workflow 调度开销。

幂等和重试要提前想好。解析任务可能因为 OOM 或节点重启被 Temporal 重试，所有写入都以文档 ID 加 chunk 序号做幂等键，重试不会产生重复向量。S3 上的中间结果（解析出的文本、表格）也缓存着，重试时已完成的阶段直接跳过。

多租户隔离贯穿全链路。数据集属于某个 AppRole 团队，所有查询强制带租户过滤条件，S3 的 key 前缀也按租户隔离，预签名 URL 带时效，防越权下载。

三条链路各走各的

整个服务拆开看就三件事：上传走对象存储直传，处理走异步工作流，检索做多路召回。Hertz 顶在 API 层，S3 承载原始文件，eino 加 pond 解决解析并发，Temporal 保证任务可靠，GaussDB 和 MongoDB 分别承接元数据和向量图谱。这套架构支撑着知识库问答服务，也给后续的知识图谱和多模态检索留了扩展空间。

封面图：motleypixel / Flickr · CC BY 2.0

从单体到账号中台：统一认证中心的架构思考

Mon, 11 Mar 2024 10:30:00 +0800

四个系统，四套登录

2023 年底我刚到某科技公司时，内部几个业务系统各有各的登录：统一支付平台一套账号，数据治理服务一套，数据集管理服务和知识库问答服务又各搞一套。员工要记四五个密码，离职了账号还关不干净；外部客户在一个系统注册完，跳到另一个系统还得再注册一次。运维和安全团队都在催：能不能统一一下。

这就是统一认证中心的起点。但很快想明白一件事：光把用户表抽出来解决不了问题，身份怎么统一、认证方式怎么扩展、应用之间怎么建立信任，这三件事都绕不开。

核心域怎么划

我把统一认证中心划成五个域：

身份域：全局唯一的 UserID（Snowflake 生成），一个用户可以绑定多种凭证，密码、手机、邮箱、微信/企微/飞书 OAuth 都行。
应用域：每个接入方有自己的 AppID/AppSecret，配置回调地址、授权方式、可用的登录 Provider。
组织域：用 AppRole 做团队/租户隔离，用户在不同应用里可以有不同角色。RBAC 权限模型落在认证中心，资源权限还是业务系统自己持有。
会话域：认证中心统一颁发 JWT（RSA 私钥签），业务系统拿 JWKS 公钥在本地验签，不回源。
Provider 域：短信、邮件、验证码、社交登录全做成可插拔接口，默认实现腾讯云 SMS/SES/Captcha，以后要换阿里或自建，加个实现就行。

技术栈上用 go-zero 拆 RPC 服务，Wire 做依赖注入，Service/DAO 分层。

分层与关键代码

整体分层这样组织：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


passport/
├── api/ # HTTP 网关 (go-zero rest)
│ ├── handler/
│ └── middleware/
├── rpc/ # gRPC 服务
│ ├── user/
│ ├── app/
│ ├── auth/
│ └── org/
├── internal/
│ ├── service/ # 业务编排
│ ├── dao/ # 数据访问
│ ├── provider/ # 可插拔 Provider
│ └── token/ # JWT 签发/JWKS
└── wire/

Provider 接口是可插拔的关键：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


type SMSProvider interface {
 Send(ctx context.Context, phone, tmplID string, params map[string]string) error
}

type EmailProvider interface {
 Send(ctx context.Context, to, subject, body string) error
}

type CaptchaProvider interface {
 Verify(ctx context.Context, ticket, randstr string) error
}

Wire 注入时按配置选择实现：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


func NewSMSProvider(cfg config.SMS) provider.SMSProvider {
 switch cfg.Provider {
 case "tencent":
 return tencent.NewSMS(cfg.Tencent)
 case "aliyun":
 return aliyun.NewSMS(cfg.Aliyun)
 default:
 return noop.NewSMS()
 }
}

登录入口用 AuthService 统一编排。不管密码、短信还是社交登录，最后都收拢到同一套"凭证换 UserID → 发 Token"的流程里：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


type AuthService struct {
 userDao dao.UserDAO
 credDao dao.CredentialDAO
 tokenSvc *token.Service
 providers provider.Container
}

func (s *AuthService) Login(ctx context.Context, req *LoginRequest) (*TokenPair, error) {
 var userID int64
 var err error
 switch req.GrantType {
 case "password":
 userID, err = s.loginByPassword(ctx, req.AppID, req.Account, req.Password)
 case "sms":
 userID, err = s.loginBySMS(ctx, req.AppID, req.Phone, req.Code)
 case "social":
 userID, err = s.loginBySocial(ctx, req.AppID, req.Provider, req.Code)
 default:
 return nil, ErrUnsupportedGrantType
 }
 if err != nil {
 return nil, err
 }
 return s.tokenSvc.Issue(ctx, userID, req.AppID)
}

JWT 签发用 RSA 私钥，公钥通过 JWKS 端点暴露：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


func (s *Service) Issue(ctx context.Context, userID int64, appID string) (*TokenPair, error) {
 now := time.Now()
 claims := Claims{
 UserID: userID,
 AppID: appID,
 RegisteredClaims: jwt.RegisteredClaims{
 Issuer: "passport",
 Subject: strconv.FormatInt(userID, 10),
 Audience: jwt.ClaimStrings{appID},
 ExpiresAt: jwt.NewNumericDate(now.Add(2 * time.Hour)),
 IssuedAt: jwt.NewNumericDate(now),
 ID: snowflake.NextID(),
 },
 }
 accessToken, err := jwt.NewWithClaims(jwt.SigningMethodRS256, claims).
 SignedString(s.privKey)
 // refresh token 省略
 return &TokenPair{AccessToken: accessToken, ...}, nil
}

最难的是用户合并

五个域里真正难缠的是身份。一个用户先用微信登录、后来又用手机号注册，识别为同一个人之后要合并。我的做法是建一张 user_bindings 表，凭证和用户是多对一关系，合并时把旧凭证挂到新 UserID 下，再写一条审计日志。

麻烦在后头：业务系统的外键引用的还是旧 UserID，得发事件通知各系统做 ID 映射。这件事比当初拍板时想的工作量大得多。

吊销、组织树和供应商灰度

JWT 吊销是个老话题。我们用短 AccessToken（2 小时）加长 RefreshToken（7 天），RefreshToken 存 Redis，随时可吊销；AccessToken 不做黑名单，靠短过期自然失效。登出只吊销 RefreshToken。支付这类安全要求极高的场景，再加一个"令牌版本号"claim，改密码时版本号递增，旧 token 立刻作废。

组织这块一开始想把组织树建在认证中心，后来发现各业务系统的组织模型差异太大：统一支付平台里是商户，数据治理服务里是团队，知识库问答服务里是企业。强行统一就是削足适履。最后认证中心只存 (app_id, user_id, role_external_id)，组织名和层级由业务系统自己维护。

Provider 也有灰度需求。腾讯云短信偶尔抖动，我在 Provider 层加了个 FanoutProvider，按权重在多家供应商之间分流，失败自动降级，配置走配置中心热更新，不用重启。

后来

统一认证中心上线之后，新业务接入 SSO 只要半天，离职员工的账号在一处关掉就全端下线，安全审计也有了统一入口。回头看，做账号中台靠的是克制：只做身份、认证、应用信任这三件事，组织和资源权限坚决留给业务系统。“登录"这件每个系统都要重复做的事，总算变成了一个可复用的平台能力。

封面图：anthony arrigo / Flickr · CC BY 2.0

支付平台三端分离架构设计：多场景统一支付的落地

Sat, 09 Dec 2023 10:30:00 +0800

支付场景太散了

我在某科技公司主导统一支付平台。支付场景很散：有面向终端用户的充值、订阅付费，有面向机构客户的对公转账和批量打款，还有运营后台的手工调账、退款审批。要是把这些逻辑全塞进一个应用，权限边界会搅在一起，发版互相影响，接口粒度也没法统一。

我的做法是三端分离、共用一个支付内核：用户端、商户端、管理端各自独立部署，底层共用支付订单、状态机、渠道适配和对账能力。

三端，一个内核

接入层用 Gin 起了三个独立服务，各自有自己的路由组和中间件链。用户端对接前端，OAuth2 登录，只有下单、查单、回调接收；商户端对接机构客户的系统，走 AppID/AppSecret 的 OpenAPI 签名认证，提供统一下单、退款、查询；管理端对接运营后台，RBAC 权限，审批、调账、对账导出都在这。

三端都不直接碰数据库，统一走 gRPC 调 payment-core。支付核心封装了订单状态机和支付渠道适配：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51


type PaymentService struct {
 db *gorm.DB
 channels map[string]Channel // channelCode -> adapter
 engine *billing.Engine // 动态计费引擎
}

type Channel interface {
 CreateOrder(ctx context.Context, order *Order) (payURL string, err error)
 QueryOrder(ctx context.Context, orderNo string) (*ChannelOrder, error)
 Refund(ctx context.Context, orderNo string, amount int64) error
 ParseCallback(req *http.Request) (*CallbackResult, error)
}

// 统一下单入口，三端最终都走到这里
func (s *PaymentService) CreateOrder(ctx context.Context, req *CreateOrderReq) (*Order, error) {
 // 1. 计费引擎算出应付金额
 amount, err := s.engine.Calculate(ctx, req.BizCode, req.Params)
 if err != nil {
 return nil, err
 }

 order := &Order{
 OrderNo: snowflake.New().NextID().String(),
 BizCode: req.BizCode,
 BizID: req.BizID,
 PayerID: req.PayerID,
 Amount: amount,
 Status: OrderStatusPending,
 Channel: req.ChannelCode,
 CreatedAt: time.Now(),
 }

 // 2. 落库
 if err := s.db.Create(order).Error; err != nil {
 return nil, err
 }

 // 3. 调起对应渠道
 ch, ok := s.channels[req.ChannelCode]
 if !ok {
 return nil, ErrChannelNotSupported
 }
 payURL, err := ch.CreateOrder(ctx, order)
 if err != nil {
 order.Status = OrderStatusFailed
 s.db.Model(order).Update("status", OrderStatusFailed)
 return nil, err
 }
 order.PayURL = payURL
 return order, nil
}

商户端的签名认证是独立中间件，除了验签还带防重放，5 分钟时间窗加 nonce 去重：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36


func MerchantSignAuth(redis *redis.Client, merchantSvc MerchantService) gin.HandlerFunc {
 return func(c *gin.Context) {
 appID := c.GetHeader("X-App-Id")
 sign := c.GetHeader("X-Sign")
 timestamp := c.GetHeader("X-Timestamp")
 nonce := c.GetHeader("X-Nonce")

 if appID == "" || sign == "" {
 c.AbortWithStatusJSON(401, gin.H{"msg": "missing auth headers"})
 return
 }
 // 防重放：5 分钟时间窗 + nonce 去重
 if math.Abs(float64(time.Now().Unix()-toInt64(timestamp))) > 300 {
 c.AbortWithStatusJSON(401, gin.H{"msg": "timestamp expired"})
 return
 }
 if ok, _ := redis.SetNX(c, "nonce:"+nonce, 1, 5*time.Minute).Result(); !ok {
 c.AbortWithStatusJSON(401, gin.H{"msg": "replayed request"})
 return
 }

 secret, err := merchantSvc.GetAppSecret(c, appID)
 if err != nil {
 c.AbortWithStatusJSON(401, gin.H{"msg": "invalid app"})
 return
 }
 // 按 method + path + timestamp + nonce + body 拼接待签名字符串
 signStr := buildSignString(c, timestamp, nonce)
 if err := rsa.Verify(secret.PublicKey, []byte(signStr), sign); err != nil {
 c.AbortWithStatusJSON(401, gin.H{"msg": "sign verify failed"})
 return
 }
 c.Set("merchant_id", secret.MerchantID)
 c.Next()
 }
}

四个权衡

第一是接口粒度。结果发现三端要的东西完全不一样：用户端要聚合后的 DTO，订单里带商品名、状态文案；商户端要稳定精简的字段，OpenAPI 不能随便加字段；管理端要全量字段加筛选分页。我们没有让 payment-core 做接口裁剪，而是三端 API 层各自组装 DTO，core 只返回领域模型，别让核心服务被展示逻辑污染。

第二是回调幂等。支付渠道的回调可能重复投递。我们用 order_no 加 channel_trade_no 做唯一索引，重复回调直接返回成功，不重复触发流转。状态机自己还有一层防护：Paid 状态再收到 PaySuccess 是空操作，不会重复发货。

第三是对账。三端共用一个对账内核，每天凌晨拉渠道对账单跟本地订单比对，差异进差错池。导出用 Excelize 流式写入，机构客户一次能导几十万行，全量加载会 OOM。数据隔离在 DAO 层用 merchant_id 强制过滤，商户端只能导出自己名下的订单。

第四是计费规则。按次、包月、阶梯价、渠道费率，不同业务线算法不一样。我们把规则抽成 Rule 接口，配置驱动，新增业务线只加规则实现和配置，不用动下单主流程。

后来

三端分离拆的其实是"谁在用"和"怎么支付"这两件事：认证、权限、DTO 组装留在接入层，状态机一致性和渠道扩展性收在核心层。支付系统还有条底线：业务代码不许直接改订单状态，所有流转都过状态机校验。

封面图：The City of Toronto / Flickr · CC BY 2.0

从 fasthttp 迁移到 go-zero：一次 C/S 到 B/S 的架构重构实录

Wed, 06 Sep 2023 10:30:00 +0800

老架构走到头了

先交代下背景。我之前在一家做宠物医疗 SaaS 的公司，老版本是典型的 C/S 架构：Windows 客户端通过 fasthttp 与服务端保持长连接，消息分发用自定义二进制协议。早期跑得很稳，但门店扩张到数千家之后，问题一个个冒出来：客户端发版困难，协议升级要双端兼容，服务端没法水平扩容，毕竟长连接是绑在节点上的。最要命的是业务逻辑全塞在一个单体里，改一个挂号流程，整个系统要全量回归。

2023 年我们决定迁到 B/S 架构，浏览器直接访问，后端选了 go-zero。

怎么拆的

go-zero 吸引我的点是它自带的微服务治理能力：熔断、限流、降级、超时控制都是开箱即用，不用自己在业务代码里堆中间件。整体拆成 API 网关层和 RPC 服务层：

API 层用 go-zero 的 .api 文件定义 RESTful 接口，通过 goctl 生成路由、handler、types 骨架。
RPC 层用 goctl rpc new 生成 gRPC 服务，按领域拆成挂号、诊疗、收费、库存四个服务。
服务注册用 etcd，网关通过 zrpc 直连 RPC 客户端，带客户端负载均衡。

下面是 .api 文件的一个片段：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


syntax = "v1"

type (
 RegisterRequest {
 PetId int64 `json:"pet_id"`
 DoctorId int64 `json:"doctor_id"`
 DeptCode string `json:"dept_code"`
 }
 RegisterResponse {
 OrderNo string `json:"order_no"`
 Status int `json:"status"`
 }
)

service clinic-api {
 @handler RegisterHandler
 post /api/v1/register (RegisterRequest) returns (RegisterResponse)
}

生成的 handler 只做参数校验和调用 logic，业务全部下沉到 logic 层，再通过 zrpc 调用下游：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


func (l *RegisterLogic) Register(req *types.RegisterRequest) (*types.RegisterResponse, error) {
 resp, err := l.svcCtx.ClinicRpc.Register(l.ctx, &clinic.RegisterReq{
 PetId: req.PetId,
 DoctorId: req.DoctorId,
 DeptCode: req.DeptCode,
 })
 if err != nil {
 return nil, err
 }
 return &types.RegisterResponse{OrderNo: resp.OrderNo, Status: int(resp.Status)}, nil
}

zrpc 的客户端在 servicecontext.go 里初始化，自带 etcd 服务发现和中间件：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


type ServiceContext struct {
 Config config.Config
 ClinicRpc clinic.ClinicClient
}

func NewServiceContext(c config.Config) *ServiceContext {
 return &ServiceContext{
 Config: c,
 ClinicRpc: clinic.NewClinicClient(zrpc.MustNewClient(c.ClinicRpc).Conn()),
 }
}

迁移路上的三个坑

第一个坑是长连接怎么下线。老客户端还有存量门店在用，不能一刀切，我们在网关侧做了一层协议适配：fasthttp 接收老协议，转成 gRPC 调用新服务，灰度了两个月才彻底切掉。期间最麻烦的是老协议没有 trace 字段，跨协议排查问题完全是黑盒，只能在适配层强制注入 traceId。

第二个坑是 goctl 模板定制。默认生成的代码结构和我们团队的 DAO 规范有出入，我们 fork 了一份 template，把 GORM 和 Zap 日志注入进去，后续新服务直接用定制模板生成，省了不少重复劳动。

第三个坑是超时配置，也是最隐蔽的一个。go-zero 的超时是分层的，API 层、RPC 客户端、RPC 服务端都要设，而且要呈"倒金字塔"：外层超时必须大于内层，否则会出现上游已经返回超时、下游还在执行的空转。我们把 API 设成 5s，RPC 设成 3s，DB 查询设成 1s，基本覆盖了业务场景。

迁完之后

从 fasthttp C/S 迁到 go-zero B/S，最大的收益不是性能，是交付节奏。浏览器即开即用，发版不再依赖客户端升级；微服务拆分之后，单个服务可以独立部署。go-zero 的工具链和治理能力，让我们在没有专职中间件团队的情况下也能把微服务跑起来，这对中小团队很实在。

封面图：cbowns / Flickr · CC BY-SA 2.0