Gin on 姚玉亮的网络日志

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

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

Gin 中间件实战：JWT 认证与请求日志异步落盘 MongoDB

Thu, 23 Nov 2023 10:30:00 +0800

审计日志一条不能丢

宠物医疗 SaaS 的 B/S 版后端需要统一的认证和审计。所有 API 请求都要校验 JWT，把用户和医院上下文提取出来；同时合规要求所有请求日志落盘，请求方法、路径、参数、响应状态码、耗时、操作者，一样不能少，保留半年备查。

同步写日志会拖慢接口响应。日志结构嵌套深、量又大，放 MySQL 里查询和归档都别扭，我选了 MongoDB，通过 channel 异步写，不阻塞主请求。

把身份塞进 Context

JWT 中间件用 golang-jwt/jwt/v5，从 Authorization 头解析 token，校验签名和过期时间，再把用户 ID、医院 ID、角色注入 gin.Context，后面的 handler 直接取用：

 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


type Claims struct {
 UserID int64 `json:"uid"`
 HospID int64 `json:"hid"`
 RoleCode string `json:"rol"`
 jwt.RegisteredClaims
}

func JWTAuth(signingKey []byte) gin.HandlerFunc {
 return func(c *gin.Context) {
 tokenStr := c.GetHeader("Authorization")
 if len(tokenStr) > 7 && tokenStr[:7] == "Bearer " {
 tokenStr = tokenStr[7:]
 }
 if tokenStr == "" {
 c.AbortWithStatusJSON(401, gin.H{"code": 401, "msg": "missing token"})
 return
 }

 claims := &Claims{}
 token, err := jwt.ParseWithClaims(tokenStr, claims, func(t *jwt.Token) (interface{}, error) {
 if _, ok := t.Method.(*jwt.SigningMethodHMAC); !ok {
 return nil, fmt.Errorf("unexpected signing method: %v", t.Header["alg"])
 }
 return signingKey, nil
 })
 if err != nil || !token.Valid {
 c.AbortWithStatusJSON(401, gin.H{"code": 401, "msg": "invalid token"})
 return
 }

 c.Set("uid", claims.UserID)
 c.Set("hid", claims.HospID)
 c.Set("rol", claims.RoleCode)
 c.Next()
 }
}

校验的时候要连签名算法一起校验，代码里那个 HMAC 断言就是干这个的，防 alg 混淆攻击。

channel 满了就写文件

日志中间件用 ResponseWriter 包装器捕获响应状态码和响应体大小，通过一个带缓冲 channel 把日志投递给后台 writer。

这里有个和埋点上报不一样的前提。埋点丢几条无所谓，审计日志一条不能丢。所以同样是非阻塞投递，channel 满时的动作不同：不丢弃，降级写本地文件。

 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
52
53
54
55
56
57
58
59
60
61
62
63
64
65


type AccessLog struct {
 TraceID string `bson:"trace_id"`
 UserID int64 `bson:"user_id"`
 HospID int64 `bson:"hosp_id"`
 Method string `bson:"method"`
 Path string `bson:"path"`
 Query string `bson:"query"`
 ClientIP string `bson:"client_ip"`
 StatusCode int `bson:"status_code"`
 Latency time.Duration `bson:"latency"`
 ReqSize int `bson:"req_size"`
 RespSize int `bson:"resp_size"`
 ErrMsg string `bson:"err_msg,omitempty"`
 CreatedAt time.Time `bson:"created_at"`
}

type bodyWriter struct {
 gin.ResponseWriter
 size int
}

func (w *bodyWriter) Write(b []byte) (int, error) {
 n, err := w.ResponseWriter.Write(b)
 w.size += n
 return n, err
}

func AccessLogMiddleware(logCh chan<- *AccessLog, fallback *os.File) gin.HandlerFunc {
 return func(c *gin.Context) {
 start := time.Now()
 bw := &bodyWriter{ResponseWriter: c.Writer}
 c.Writer = bw

 c.Next()

 entry := &AccessLog{
 TraceID: c.GetString("trace_id"),
 Method: c.Request.Method,
 Path: c.Request.URL.Path,
 Query: c.Request.URL.RawQuery,
 ClientIP: c.ClientIP(),
 StatusCode: c.Writer.Status(),
 Latency: time.Since(start),
 ReqSize: int(c.Request.ContentLength),
 RespSize: bw.size,
 CreatedAt: start,
 }
 if uid, ok := c.Get("uid"); ok {
 entry.UserID = uid.(int64)
 }
 if hid, ok := c.Get("hid"); ok {
 entry.HospID = hid.(int64)
 }
 if len(c.Errors) > 0 {
 entry.ErrMsg = c.Errors.String()
 }

 select {
 case logCh <- entry:
 default:
 // channel 满，降级写本地文件，保证审计日志不丢
 json.NewEncoder(fallback).Encode(entry)
 }
 }
}

后台 writer 攒批写 MongoDB，用的是 BulkWrite：

 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


func LogWriter(ctx context.Context, coll *mongo.Collection, ch <-chan *AccessLog) {
 batch := make([]mongo.WriteModel, 0, 200)
 ticker := time.NewTicker(500 * time.Millisecond)
 defer ticker.Stop()

 flush := func() {
 if len(batch) == 0 {
 return
 }
 _, err := coll.BulkWrite(ctx, batch)
 if err != nil {
 log.Printf("mongo bulk write error: %v", err)
 }
 batch = batch[:0]
 }

 for {
 select {
 case e := <-ch:
 m := mongo.NewInsertOneModel().SetDocument(e)
 batch = append(batch, m)
 if len(batch) >= 200 {
 flush()
 }
 case <-ticker.C:
 flush()
 case <-ctx.Done():
 flush()
 return
 }
 }
}

四个坑

第一个坑是请求体。最开始我直接把 c.Request.Body 读出来记日志，读完之后后续 handler 再读就是空的：body 是个流，读一次就没了。要用 io.NopCloser 加 bytes.Buffer 复制一份放回去。另外大 body 必须截断，只记前 1KB，不然日志体积很快失控。

第二个是敏感字段。密码、身份证、手机号不能明文进日志。我在序列化前对 query 和 body 里的 password、id_card、phone 做了掩码。这事必须在入口做，等数据入了库再补救就晚了，合规也不认。

第三个是 MongoDB 写入延迟。BulkWrite 攒到 200 条批量写，平时延迟很稳，但副本集发生主从切换时写入会短暂失败。flush 失败就把批次写回本地文件，一个补传任务定期扫描重放，保证审计数据最终不丢。

第四个是 JWT 的注销。JWT 无状态，token 在过期前没法主动作废。我们在 Redis 里维护黑名单：退出登录或改密码时把 jti 加进去，TTL 设成剩余有效期。代价是每个请求多一次 Redis 查询，我觉得值。

后来

这两个中间件后来成了我所有 Go Web 项目的基础组件。回头看，主流程都不难，难的全是边角：body 读完要放回，日志要异步但不能丢，token 要能注销，敏感字段要在入口脱敏。边角处理好了，才算能用。

封面图：Tawheed Manzoor / Flickr · CC BY 2.0