第10章 · 单体拆分微服务（正式版）

// 没有 RPC 时，跨进程调用你得自己拼 HTTP 请求、解析 JSON，写得像"发邮件"
resp, _ := http.Post("http://user-service:8080/get?uid=1", ...)
body, _ := io.ReadAll(resp.Body)
// 再手动把 body 解析成结构体……啰嗦且易错

// 有了 RPC（gRPC）后，写起来像"打电话"，和本地调用几乎一样
user, err := client.GetUserByID(ctx, &GetUserByIDRequest{UserId: 1})

微服务（架构）  ── 不规定通信方式，三种都能用
  ├─ HTTP   （应用层协议）        → 可以走 RESTful 风格
  ├─ RPC    （通信协议思想）      → 像调本地函数
  │     └─ gRPC（具体 RPC 框架，基于 HTTP/2 + Protobuf）
  └─ MQ     （消息队列，异步通信）

// 一个最简单的 .proto 文件：定义"用户"这个数据结构和服务方法
syntax = "proto3";
package user.v1;

// message = 数据结构（相当于 Go 的 struct）
message User {
  int64 id = 1;       // 数字 1 是"字段编号"，序列化时只传编号不传名字
  string nickname = 2;
}

// service = 远程能调的方法（相当于 Go 的 interface）
service UserService {
  rpc GetUserByID(GetUserByIDRequest) returns (User);
}
message GetUserByIDRequest { int64 user_id = 1; }

// gRPC 让你像打本地电话一样调远程方法，出入参都是 proto 生成的强类型结构
conn, _ := grpc.Dial("localhost:9090", grpc.WithTransportCredentials(insecure.NewCredentials()))
client := userv1.NewUserServiceClient(conn)
// 下面这行，写起来像本地调用，实际走了一次 HTTP/2 + Protobuf 的网络往返
resp, err := client.GetUserByID(ctx, &userv1.GetUserByIDRequest{UserId: 1})

// 服务端流式：客户端发一次，服务端用 for 循环不断 Send 回多条
rpc WatchLogs(LogRequest) returns (stream LogEntry);

// 客户端流式：客户端用 Send 不断发，最后 Recv 一次拿汇总
rpc UploadChunks(stream Chunk) returns (UploadSummary);

// 双向流式：两边都能随时 Send，典型如聊天、实时推送
rpc Chat(stream Message) returns (stream Message);

// 文件路径: content-community/api/proto/interactive/v1/interactive.proto
// 声明使用 proto3 语法（除非维护老系统，否则都用 proto3）
syntax = "proto3";

// 生成 Go 代码时的包路径配置（必须包含 . 或 /）
option go_package = "github.com/yourname/content-community/api/proto/interactive/v1;interactivev1";

// 包名（可选，没什么实际作用）
package interactive.v1;

// 服务定义：相当于 Go 中的 interface
service InteractiveService {
  // 每个方法：一个请求 message，一个响应 message
  rpc Like(LikeRequest) returns (LikeResponse);
  rpc CancelLike(CancelLikeRequest) returns (CancelLikeResponse);
  rpc Collect(CollectRequest) returns (CollectResponse);
  rpc Get(GetRequest) returns (GetResponse);
}

// 点赞请求
message LikeRequest {
  string biz = 1;    // biz 标识业务类型，如 "article" 或 "comment"
  int64 biz_id = 2;  // 业务 ID
  int64 uid = 3;     // 用户 ID
}

message LikeResponse {}   // 空响应：用 {} 表示"只关心成功失败"

# 安装 Go 和 gRPC 代码生成插件（只装一次）
go install google.golang.org/protobuf/cmd/protoc-gen-go@v1.28
go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@v1.2
# 务必把 $GOPATH/bin 加入 PATH，否则 protoc 找不到插件

# 编译：生成 .pb.go 和 _grpc.pb.go
protoc \
  --go_out=. --go_opt=paths=source_relative \
  --go-grpc_out=. --go-grpc_opt=paths=source_relative \
  api/proto/interactive/v1/interactive.proto

// 文件路径: content-community/internal/interactive/grpc/server.go
package grpc

import (
	"context"
	interactivev1 "github.com/yourname/content-community/api/proto/interactive/v1"
	"github.com/yourname/content-community/internal/interactive/service"
)

// GRPCServer 实现 protoc 生成的服务端接口。
// 必须嵌入 UnimplementedInteractiveServiceServer：以后接口新增方法时编译不失败（向前兼容）。
type GRPCServer struct {
	interactivev1.UnimplementedInteractiveServiceServer
	svc *service.InteractiveService
}

func NewGRPCServer(svc *service.InteractiveService) *GRPCServer {
	return &GRPCServer{svc: svc}
}

// Like 实现点赞接口。签名固定：context + 请求 message + error。
func (s *GRPCServer) Like(ctx context.Context, req *interactivev1.LikeRequest) (
	*interactivev1.LikeResponse, error) {
	// 从请求取参 → 委托领域服务处理 → 返回空响应
	err := s.svc.Like(ctx, req.GetBiz(), req.GetBizId(), req.GetUid())
	return &interactivev1.LikeResponse{}, err
}

// 文件路径: content-community/internal/interactive/main.go（节选）
package main

func main() {
	// 创建监听端口
	lis, err := net.Listen("tcp", ":8091")
	if err != nil {
		panic(err)
	}
	// 初始化依赖（wire 生成），拿到 GRPCServer
	app := wirex.NewApp()
	server := app.GRPCServer
	log.Println("interactive gRPC listening on :8091")
	// Serve 会阻塞，直到出错或进程退出
	if err = server.Serve(lis); err != nil {
		panic(err)
	}
}

// 文件路径: content-community/internal/web/client/interactive.go
package client

import (
	"context"
	"math/rand"
	interactivev1 "github.com/yourname/content-community/api/proto/interactive/v1"
)

type InteractiveClient struct {
	remote    interactivev1.InteractiveServiceClient // 真实 gRPC 客户端
	local     interactivev1.InteractiveServiceClient // 本地适配的 gRPC 客户端
	threshold int32                                  // 流量阈值 0~100，走远程的概率
}

// Get 按"随机数 + 阈值"决定走本地还是远程——这是灰度的核心开关
func (c *InteractiveClient) Get(ctx context.Context, biz string, bizId, uid int64) (
	*interactivev1.GetResponse, error) {
	randNum := rand.Int31n(100)
	if randNum < c.threshold {
		return c.remote.Get(ctx, &interactivev1.GetRequest{Biz: biz, BizId: bizId, Uid: uid})
	}
	return c.local.Get(ctx, &interactivev1.GetRequest{Biz: biz, BizId: bizId, Uid: uid})
}

message User {
  reserved 3, 5;           // 3、5 号字段已删除：编号从此封存，禁止再用
  reserved "old_nickname"; // 字段名也占位，防止新字段沿用老名字
  int64 id = 1;
  string nickname = 2;
}

message BatchGetRequest {
  string biz = 1;
  repeated int64 biz_ids = 2; // Go 里生成 []int64
}

message Counters {
  map<string, int64> counters = 1; // Go 里生成 map[string]int64
}

message Filter {
  oneof by {
    string uid = 1;  // 设了 uid 就不能再设 cid
    int64 cid = 2;
  }
}

enum Status {
  Unknown = 0;  // 0 不要用于业务，占位
  Active = 1;
  Inactive = 2;
}

# buf.gen.yaml：buf 的代码生成配置（字段细节以官方文档为准）
version: v1
managed:
  enabled: true
  # 统一配置 go_package 前缀，每个 proto 里就省去老长一段
  go_package_prefix:
    default: github.com/yourname/content-community/api/proto
plugins:
  - plugin: go        # Go 结构体代码插件
    out: .
    opt: paths=source_relative
  - plugin: go-grpc   # gRPC 服务端/客户端代码插件
    out: .
    opt: paths=source_relative

// 步骤 1：建立到服务端的连接（返回的是连接抽象，不是单个 socket）
conn, err := grpc.Dial("localhost:8091",
	// 测试环境跳过 TLS；生产环境要配证书
	grpc.WithTransportCredentials(insecure.NewCredentials()),
)
if err != nil {
	panic(err)
}
defer conn.Close()

// 步骤 2：用连接初始化客户端
client := interactivev1.NewInteractiveServiceClient(conn)

// 步骤 3：发起调用（此时才可能真正建网络连接——懒连接）
resp, err := client.Get(ctx, &interactivev1.GetRequest{ /* ... */ })

限界上下文(销售部) ≈ 一个微服务
  └─ 聚合体(一次销售闭环) = 聚合根(订单) + 值对象(金额, 地址)
       └─ 只能通过 订单ID 引用别的聚合根
       └─ 仓储 Repository 负责把它存进数据库

webook/                 ← 仍是单个进程、单个仓库、一起部署
├── internal/
│   ├── user/           ← 用户模块（自己一棵子树）
│   ├── post/           ← 帖子模块
│   ├── interactive/    ← 互动模块
│   └── common/         ← 跨模块共享的值对象
└── main.go             ← 一个 main，全部一起编译部署

// 概念示意：监听配置变更，实时调整阈值（生产用配置中心，如 Nacos/Apollo/etcd）
configClient.Subscribe("interactive.threshold", func(val string) {
	threshold, _ := strconv.Atoi(val)
	client.UpdateThreshold(int32(threshold)) // 立即生效，所有节点同步
})

content-community/
├── api/
│   └── proto/
│       └── interactive/
│           └── v1/
│               ├── interactive.proto
│               └── gen/         # 编译产物
└── internal/

// 文件路径: internal/post/grpc/user_client.go（节选）
// 只建一次客户端连接，所有并发调用都复用它
conn, _ := grpc.NewClient("127.0.0.1:9090",
	grpc.WithTransportCredentials(insecure.NewCredentials()))
defer conn.Close()
client := userv1.NewUserServiceClient(conn)

var wg sync.WaitGroup
for i := 0; i < 100; i++ {
	wg.Add(1)
	go func(i int) {
		defer wg.Done()
		// 100 个 goroutine 同时调用，底层复用同一个 ClientConn（同一条 HTTP/2 连接）
		_, _ = client.GetUserByID(context.Background(),
			&userv1.GetUserByIDRequest{UserId: int64(i)})
	}(i)
}
wg.Wait()

go run ./cmd/webook          # 终端 1：起服务端
# 终端 2：跑并发调用后，观察到 :9090 的连接数
netstat -an | grep ESTABLISHED | grep 9090
# 预期：连接数是 1~2 条，而不是 100 条——请求共享了同一条 HTTP/2 连接

// 文件路径: internal/user/ioc/grpc.go（服务端，完整落地见第 8 步）
s := grpc.NewServer(
	grpc.KeepaliveParams(keepalive.ServerParameters{
		MaxConnectionIdle: 5 * time.Minute,  // 空闲超过 5 分钟就回收（并提示客户端换连接）
		MaxConnectionAge:  2 * time.Hour,    // 单条连接最长活 2 小时，到点优雅 GOAWAY
		Time:              10 * time.Second, // 每隔 10 秒发一次 PING
		Timeout:           5 * time.Second,  // 等 ACK 的超时；超了就判定连接已死
	}),
	grpc.KeepaliveEnforcementPolicy(keepalive.EnforcementPolicy{
		MinTime:             5 * time.Second, // 客户端的 PING 间隔比这还小 => 视为骚扰，直接断连
		PermitWithoutStream: true,            // 没有活跃请求时也允许保活
	}),
)

// 文件路径: internal/post/grpc/user_client.go（客户端）
conn, _ := grpc.NewClient(addr,
	grpc.WithKeepaliveParams(keepalive.ClientParameters{
		Time:                10 * time.Second, // 每隔 10 秒探一次
		Timeout:             5 * time.Second,  // 5 秒收不到 ACK 就当连接已死
		PermitWithoutStream: true,             // 空闲连接也保活
	}),
)

// 文件路径: internal/user/grpc/server.go（服务端：用 status 返回规范错误）
func (s *UserServiceServer) GetUserByID(ctx context.Context, req *userv1.GetUserByIDRequest) (
	*userv1.GetUserByIDResponse, error) {
	if req.GetUserId() <= 0 {
		// 参数错误用 InvalidArgument；若写成 return errors.New(...)，客户端只会收到 Unknown
		return nil, status.Error(codes.InvalidArgument, "user_id 必须为正数")
	}
	u, err := s.svc.GetUserByID(ctx, req.GetUserId())
	if err != nil {
		// 业务上的"查无此人"用 NotFound；真正的内部错误才用 Internal（且不要暴露 SQL 细节）
		return nil, status.Error(codes.NotFound, "用户不存在")
	}
	return &userv1.GetUserByIDResponse{User: toProto(u)}, nil
}

// 文件路径: internal/post/grpc/user_client.go（客户端：按状态码分支）
resp, err := c.remote.GetUserByID(ctx, &userv1.GetUserByIDRequest{UserId: id})
if err != nil {
	st, _ := status.FromError(err) // 把 error 解析回 status（含 code + message）
	switch st.Code() {
	case codes.NotFound:
		// 作者已注销：不当作系统故障，返回默认作者信息（业务降级）
		return common.UserBasicInfo{Id: id, Nickname: "已注销用户"}, nil
	case codes.Unavailable, codes.DeadlineExceeded:
		// 下游不可用或超时：交给熔断 / 重试 / 降级策略处理（第 14 章）
		return common.UserBasicInfo{}, fmt.Errorf("user 服务暂时不可用: %w", err)
	default:
		// 其它错误：记日志、向上抛
		return common.UserBasicInfo{}, fmt.Errorf("gRPC 查询用户 %d: %w", id, err)
	}
}
u := resp.GetUser()
return common.UserBasicInfo{Id: u.GetId(), Nickname: u.GetNickname(), Avatar: u.GetAvatar()}, nil

// 文件路径: api/proto/common/v1/response.proto
import "google/protobuf/any.proto";

message Response {
  int32  code    = 1;           // 业务码，0 表示成功
  string message = 2;
  google.protobuf.Any data = 3; // 任意业务数据"装箱"，取出时再拆
}

// 文件路径: internal/post/grpc/user_client.go（拆箱 Any）
var user userv1.User
if err := anypb.UnmarshalTo(resp.GetData(), &user, proto.UnmarshalOptions{}); err != nil {
	return err
}

// 文件路径: internal/post/grpc/user_client.go（客户端：注入 traceId + 3 秒超时）
md := metadata.Pairs("x-trace-id", traceID)            // traceID 由调用方生成（第 8 步给出简化实现）
ctx := metadata.NewOutgoingContext(context.Background(), md)
ctx, cancel := context.WithTimeout(ctx, 3*time.Second) // 计时器：deadline 会自动传给下游
defer cancel()

resp, err := c.remote.GetUserByID(ctx, &userv1.GetUserByIDRequest{UserId: uid})

// 文件路径: internal/user/grpc/server.go（服务端：读面单 + 感知取消）
func (s *UserServiceServer) GetUserByID(ctx context.Context, req *userv1.GetUserByIDRequest) (
	*userv1.GetUserByIDResponse, error) {
	if md, ok := metadata.FromIncomingContext(ctx); ok {
		// 取出 traceId 打进日志：跨服务的日志就能按同一条请求串起来（第 08 章）
		if vals := md.Get("x-trace-id"); len(vals) > 0 {
			logger.Info("收到请求", zap.String("trace_id", vals[0]))
		}
	}
	select {
	case <-time.After(100 * time.Millisecond): // 模拟真实业务耗时
		return &userv1.GetUserByIDResponse{}, nil
	case <-ctx.Done(): // 上游取消 / 超时：立刻退出，不浪费 CPU 和数据库资源
		return nil, status.Error(codes.DeadlineExceeded, "上游已取消")
	}
}

// 文件路径: internal/user/ioc/grpc.go（服务端：开启 TLS）
creds, err := credentials.NewServerTLSFromFile("configs/certs/server.crt", "configs/certs/server.key")
if err != nil {
	panic(err) // 证书读不到就让启动失败——绝不允许"悄悄降级成明文"
}
s := grpc.NewServer(grpc.Creds(creds), grpc.UnaryInterceptor(AuthInterceptor))

// 文件路径: internal/post/grpc/credentials.go（客户端：请求级凭证）
type tokenAuth struct{ token string }

// GetRequestMetadata：每次请求把 token 塞进 metadata，服务端拦截器里就能取到
func (t tokenAuth) GetRequestMetadata(ctx context.Context, uri ...string) (map[string]string, error) {
	return map[string]string{"authorization": t.token}, nil
}

// RequireTransportSecurity：要求必须走 TLS 才允许发送
func (t tokenAuth) RequireTransportSecurity() bool { return true }

// 文件路径: internal/user/grpc/interceptor.go（服务端：统一鉴权，业务零侵入）
func AuthInterceptor(ctx context.Context, req any, info *grpc.UnaryServerInfo,
	handler grpc.UnaryHandler) (any, error) {
	md, ok := metadata.FromIncomingContext(ctx)
	if !ok || len(md.Get("authorization")) == 0 {
		return nil, status.Error(codes.Unauthenticated, "missing token")
	}
	return handler(ctx, req) // 校验通过才进入业务代码
}

# 生成自签证书（生产环境用公司 CA 或证书管理系统签发）
openssl req -x509 -newkey rsa:2048 -nodes \
  -keyout configs/certs/server.key -out configs/certs/server.crt \
  -days 365 -subj "/CN=localhost" \
  -addext "subjectAltName=DNS:localhost,IP:127.0.0.1"
# 预期：configs/certs/ 下出现 server.crt、server.key 两个文件

// 文件路径: internal/post/grpc/user_client.go
creds, err := credentials.NewClientTLSFromFile(v.GetString("grpc.tls.cert_file"), "")
conn, err := grpc.NewClient(v.GetString("user.grpc.addr"),
	grpc.WithTransportCredentials(creds),
	grpc.WithPerRPCCredentials(tokenAuth{token: v.GetString("grpc.auth.token")}), // token 从配置 / 环境变量注入
)

// 文件路径: internal/user/grpc/server_test.go
func TestGetUserByID(t *testing.T) {
	// ① 用内存 listener 起"真"服务端：注册、拦截器、业务逻辑一样不少，只是不走网卡
	lis := bufconn.Listen(1024 * 1024)
	s := grpc.NewServer()
	userv1.RegisterUserServiceServer(s, NewUserServiceServer(newTestService(t)))
	go func() { _ = s.Serve(lis) }()
	defer s.Stop()

	// ② 客户端用自定义 dialer 连内存 listener，而不是 TCP 地址
	dialer := func(context.Context, string) (net.Conn, error) { return lis.Dial() }
	conn, err := grpc.NewClient("passthrough:///bufnet",
		grpc.WithContextDialer(dialer),
		grpc.WithTransportCredentials(insecure.NewCredentials()), // 进程内测试，无需 TLS
	)
	if err != nil {
		t.Fatalf("连接 bufnet 失败: %v", err)
	}
	defer conn.Close()

	// ③ 之后就像调真实 gRPC 一样调它
	client := userv1.NewUserServiceClient(conn)
	resp, err := client.GetUserByID(context.Background(), &userv1.GetUserByIDRequest{UserId: 1})
	if err != nil {
		t.Fatalf("GetUserByID 失败: %v", err)
	}
	if resp.GetUser().GetNickname() == "" {
		t.Fatal("昵称不应为空")
	}
}

go test ./internal/user/grpc/ -run TestGetUserByID -v
# 预期：--- PASS: TestGetUserByID (0.00s)
# 注意：不监听任何端口，不需要先启动 webook，也不连数据库

internal/
├── common/types.go    # ★ 跨模块共享的值对象（只有字段，没有逻辑）
├── user/              # 用户模块（内部分层见下方 DDD 说明）
├── post/              # 帖子模块（结构同 user）
├── interaction/       # 互动模块：第 07 章代码整体挪入
├── rank/              # 榜单模块：第 09 章代码整体挪入
├── sms/               # 短信模块
└── notification/      # 通知模块（预留空目录）

// internal/common/types.go
package common

// UserBasicInfo 是跨模块共享的「用户基础信息」值对象。
// 刻意不放 Email 等敏感字段：对外暴露越少，模块内部改动波及面越小。
type UserBasicInfo struct {
	Id       int64  `json:"id"`
	Nickname string `json:"nickname"`
	Avatar   string `json:"avatar"`
}

// internal/user/domain/user.go
package domain

import "context"

// User 是 user 模块内部的领域模型，Email 等完整字段绝不外泄到其他模块。
type User struct {
	Id       int64
	Email    string
	Nickname string
	Avatar   string
}

// UserRepository 仓储接口：service 只依赖抽象，不依赖 GORM 实现
type UserRepository interface {
	GetByID(ctx context.Context, id int64) (User, error)
	GetByIDs(ctx context.Context, ids []int64) ([]User, error)
	GetByEmail(ctx context.Context, email string) (User, error)
}

// internal/user/api.go
package user

import (
	"context"

	"github.com/yourname/content-community/internal/common"
	"github.com/yourname/content-community/internal/user/domain"
	"github.com/yourname/content-community/internal/user/service"
)

// UserModule 是 user 模块对外暴露的唯一入口。铁律：其他模块只能依赖这个接口，
// 绝不能 import user 包的 service/repository；第 5 步换成 gRPC 实现时 post 一行都不用改。
type UserModule interface {
	GetUserByID(ctx context.Context, id int64) (common.UserBasicInfo, error)
}

// UserAPI 是 UserModule 的本地实现：把领域模型「翻译」成共享的 UserBasicInfo
type UserAPI struct {
	svc *service.UserService
}

func NewUserAPI(svc *service.UserService) *UserAPI {
	return &UserAPI{svc: svc}
}

func (a *UserAPI) GetUserByID(ctx context.Context, id int64) (common.UserBasicInfo, error) {
	u, err := a.svc.GetUserByID(ctx, id)
	if err != nil {
		return common.UserBasicInfo{}, err
	}
	return toBasicInfo(u), nil
}

// toBasicInfo 领域模型 -> 共享值对象（字段裁剪集中在此）
func toBasicInfo(u domain.User) common.UserBasicInfo {
	return common.UserBasicInfo{Id: u.Id, Nickname: u.Nickname, Avatar: u.Avatar}
}

// internal/post/service/post.go
package service

import (
	"context"
	"fmt"

	"github.com/yourname/content-community/internal/common"
	"github.com/yourname/content-community/internal/post/domain"
	"github.com/yourname/content-community/internal/user"
)

// PostService 依赖 user 模块的「接口」而非实现——模块化单体的核心约束
type PostService struct {
	repo  domain.PostRepository
	users user.UserModule
}

func NewPostService(repo domain.PostRepository, users user.UserModule) *PostService {
	return &PostService{repo: repo, users: users}
}

// PostDetail 帖子详情 = 帖子本体 + 作者信息（作者来自 user 模块）
type PostDetail struct {
	Post   domain.Post          `json:"post"`
	Author common.UserBasicInfo `json:"author"`
}

// Detail 先查自己的帖子，再通过接口向 user 模块要作者信息
func (s *PostService) Detail(ctx context.Context, id int64) (PostDetail, error) {
	post, err := s.repo.GetByID(ctx, id)
	if err != nil {
		return PostDetail{}, fmt.Errorf("查询帖子: %w", err)
	}
	author, err := s.users.GetUserByID(ctx, post.AuthorId)
	if err != nil {
		return PostDetail{}, fmt.Errorf("查询作者信息: %w", err)
	}
	return PostDetail{Post: *post, Author: author}, nil
}

go build ./... && go test ./...
# 预期：编译无输出；原有测试全部 PASS（模块化挪包不该改变任何行为）

// api/proto/user/v1/user.proto
syntax = "proto3";

// go_package 决定生成代码落盘位置：api/gen/user/v1，包名 userv1
option go_package = "github.com/yourname/content-community/api/gen/user/v1;userv1";

package user.v1;

// 用户服务：对应 UserModule 的方法，外加按邮箱查询（登录用）
service UserService {
  rpc GetUserByID(GetUserByIDRequest) returns (GetUserByIDResponse);
  rpc GetUsersByIDs(GetUsersByIDsRequest) returns (GetUsersByIDsResponse);
  rpc GetUserByEmail(GetUserByEmailRequest) returns (GetUserByEmailResponse);
}

message User {
  int64 id = 1;
  string email = 2;
  string nickname = 3;
  string avatar = 4;
}

message GetUserByIDRequest { int64 user_id = 1; }
message GetUserByIDResponse { User user = 1; }
message GetUsersByIDsRequest { repeated int64 user_ids = 1; } // repeated -> []int64
message GetUsersByIDsResponse { repeated User users = 1; }
message GetUserByEmailRequest { string email = 1; }
message GetUserByEmailResponse { User user = 1; }

// api/proto/post/v1/post.proto
syntax = "proto3";

option go_package = "github.com/yourname/content-community/api/gen/post/v1;postv1";

package post.v1;

// post 服务本章只定义接口、暂不实现服务端（拆它还早）
service PostService {
  rpc GetPostByID(GetPostByIDRequest) returns (GetPostByIDResponse);
}

message Post {
  int64 id = 1;
  string title = 2;
  string content = 3;
  int64 author_id = 4;
}

message GetPostByIDRequest { int64 post_id = 1; }
message GetPostByIDResponse { Post post = 1; }

protoc \
  --go_out=. --go_opt=module=github.com/yourname/content-community \
  --go-grpc_out=. --go-grpc_opt=module=github.com/yourname/content-community \
  api/proto/user/v1/user.proto \
  api/proto/post/v1/post.proto

ls api/gen/user/v1 api/gen/post/v1
# 预期：两个目录下各有 *.pb.go 与 *_grpc.pb.go（含义见 3.8.3 节）

// internal/user/grpc/server.go
package grpc

import (
	"context"

	userv1 "github.com/yourname/content-community/api/gen/user/v1"
	"github.com/yourname/content-community/internal/user/domain"
	"github.com/yourname/content-community/internal/user/service"
)

// UserServiceServer 实现 protoc 生成的 UserServiceServer 接口。
// 必须嵌入 UnimplementedUserServiceServer（向前兼容，见 3.8.4 节提示框）。
type UserServiceServer struct {
	userv1.UnimplementedUserServiceServer
	svc *service.UserService
}

func NewUserServiceServer(svc *service.UserService) *UserServiceServer {
	return &UserServiceServer{svc: svc}
}

// GetUserByID gRPC 版查单个用户：出入参全部是 proto 生成的 message。
func (s *UserServiceServer) GetUserByID(ctx context.Context, req *userv1.GetUserByIDRequest) (
	*userv1.GetUserByIDResponse, error) {
	// 取字段用 GetXxx：字段没赋值时安全返回零值，不会 panic
	u, err := s.svc.GetUserByID(ctx, req.GetUserId())
	if err != nil {
		return nil, err
	}
	return &userv1.GetUserByIDResponse{User: toProto(u)}, nil
}

// toProto 领域模型 -> proto 消息，字段转换集中在一处
func toProto(u domain.User) *userv1.User {
	return &userv1.User{Id: u.Id, Email: u.Email, Nickname: u.Nickname, Avatar: u.Avatar}
}

// internal/user/ioc/grpc.go
package ioc

import (
	"context"
	"time"

	"google.golang.org/grpc"
	"google.golang.org/grpc/reflection"
	"go.uber.org/zap"

	userv1 "github.com/yourname/content-community/api/gen/user/v1"
	usergrpc "github.com/yourname/content-community/internal/user/grpc"
	"github.com/yourname/content-community/pkg/logger"
)

// InitGRPCServer 创建带拦截器的 gRPC Server 并注册用户服务
func InitGRPCServer(l *logger.Logger, svc *usergrpc.UserServiceServer) *grpc.Server {
	s := grpc.NewServer(grpc.ChainUnaryInterceptor(
		logInterceptor(l), // 访问日志；recovery 拦截器同理补挂
	))
	userv1.RegisterUserServiceServer(s, svc)
	// 注册反射服务：让 grpcurl 等调试工具能直接列出并调用接口
	reflection.Register(s)
	return s
}

// logInterceptor：每个 gRPC 请求打一条 zap 访问日志（与 HTTP 同规格）
func logInterceptor(l *logger.Logger) grpc.UnaryServerInterceptor {
	return func(ctx context.Context, req any, info *grpc.UnaryServerInfo,
		handler grpc.UnaryHandler) (resp any, err error) {
		start := time.Now()
		resp, err = handler(ctx, req)
		l.Info("gRPC 调用", zap.String("method", info.FullMethod),
			zap.Duration("cost", time.Since(start)), zap.Error(err))
		return resp, err
	}
}

// cmd/webook/main.go（关键改动；viper/zap/db/redis 等初始化沿用上一章）
func main() {
	// ……上一章的初始化：配置、日志、DB、Redis、各模块组装……

	httpSrv := server.NewWebServer(postHandler, userHandler)
	grpcSrv := userioc.InitGRPCServer(logger, usergrpc.NewUserServiceServer(userSvc))
	lis, err := net.Listen("tcp", ":9090")
	if err != nil {
		panic(err)
	}

	// 两个 server 并行跑；任何一个出错退出，整个进程一起退
	var g errgroup.Group
	g.Go(func() error { logger.Info("HTTP listening on :8080"); return httpSrv.Run(":8080") })
	g.Go(func() error { logger.Info("user gRPC listening on :9090"); return grpcSrv.Serve(lis) })
	if err = g.Wait(); err != nil {
		logger.Error("服务退出", zap.Error(err))
	}
}

go build ./... && go run ./cmd/webook
# 预期两条启动日志：HTTP listening on :8080 / user gRPC listening on :9090
# 另开终端调 gRPC（brew install grpcurl），预期返回用户 JSON（int64 渲染为字符串）：
grpcurl --plaintext -d '{"user_id": 1}' 127.0.0.1:9090 user.v1.UserService/GetUserByID

// internal/post/grpc/user_client.go
package grpc

import (
	"context"
	"fmt"
	"time"

	"google.golang.org/grpc"

	userv1 "github.com/yourname/content-community/api/gen/user/v1"
	"github.com/yourname/content-community/internal/common"
	"github.com/yourname/content-community/internal/user"
)

// GRPCUserClient 通过 gRPC 远程调用 user 服务，实现 UserModule 接口——
// post 拿到的仍是接口，从本地切到它时调用方零改动
type GRPCUserClient struct {
	remote userv1.UserServiceClient
}

// 编译期检查接口实现，漏实现方法在 go build 时就报错
var _ user.UserModule = (*GRPCUserClient)(nil)

func NewGRPCUserClient(conn *grpc.ClientConn) *GRPCUserClient {
	return &GRPCUserClient{remote: userv1.NewUserServiceClient(conn)}
}

func (c *GRPCUserClient) GetUserByID(ctx context.Context, id int64) (common.UserBasicInfo, error) {
	// 铁律：RPC 必须带超时，否则 user 服务一挂，post 的 HTTP 请求全部跟着挂死
	ctx, cancel := context.WithTimeout(ctx, 3*time.Second)
	defer cancel()

	resp, err := c.remote.GetUserByID(ctx, &userv1.GetUserByIDRequest{UserId: id})
	if err != nil {
		return common.UserBasicInfo{}, fmt.Errorf("gRPC 查询用户 %d: %w", id, err)
	}
	u := resp.GetUser()
	return common.UserBasicInfo{Id: u.GetId(), Nickname: u.GetNickname(), Avatar: u.GetAvatar()}, nil
}

# configs/config.yaml 新增两段
user:
  grpc:
    addr: "127.0.0.1:9090"   # 本章静态配置；第 12 章引入注册中心后删除
post:
  use_grpc_user: true         # true=post 走 gRPC 取用户信息；false=走进程内本地调用

// cmd/webook/main.go（组装部分，其余初始化沿用上一章）
userSvc := userservice.NewUserService(userRepo)
var userModule user.UserModule
if viper.GetBool("post.use_grpc_user") {
	// 远程模式：post 通过 gRPC 调 user 服务（本章新链路）
	userModule = postgrpc.NewGRPCUserClient(postioc.InitUserConn(viper))
} else {
	userModule = user.NewUserAPI(userSvc) // 本地模式：进程内直接调用（回滚目标）
}
postSvc := postservice.NewPostService(postRepo, userModule) // post 拿到的是接口

# 终端 1 启动（use_grpc_user: true），终端 2 请求帖子详情，预期返回：
# {"code":0,"msg":"success","data":{"post":{...},"author":{"id":1,"nickname":"月亮湾船长",...}}}
curl -s localhost:8080/api/post/1
# 终端 1 出现 gRPC 调用日志（证明走的是远程链路）：
# {"level":"info","msg":"gRPC 调用","method":"/user.v1.UserService/GetUserByID"}

// 文件路径: internal/user/grpc/server_test.go
package grpc

import (
	"context"
	"net"
	"testing"

	"google.golang.org/grpc"
	"google.golang.org/grpc/credentials/insecure"
	"google.golang.org/grpc/test/bufconn"

	userv1 "github.com/yourname/content-community/api/gen/user/v1"
)

func TestGetUserByID(t *testing.T) {
	// ① 内存 listener：注册、拦截器、业务逻辑一个不少，只是不走网卡
	lis := bufconn.Listen(1024 * 1024)
	s := grpc.NewServer()
	userv1.RegisterUserServiceServer(s, NewUserServiceServer(newTestUserService(t)))
	go func() { _ = s.Serve(lis) }()
	defer s.Stop()

	// ② 自定义 dialer：把"拨号"重定向到内存 listener，绕开 TCP 与端口
	dialer := func(context.Context, string) (net.Conn, error) { return lis.Dial() }
	conn, err := grpc.NewClient("passthrough:///bufnet",
		grpc.WithContextDialer(dialer),
		grpc.WithTransportCredentials(insecure.NewCredentials()), // 进程内测试无需 TLS
	)
	if err != nil {
		t.Fatalf("连接 bufnet 失败: %v", err)
	}
	defer conn.Close()

	// ③ 之后就像调真实 gRPC 一样调它
	client := userv1.NewUserServiceClient(conn)
	resp, err := client.GetUserByID(context.Background(), &userv1.GetUserByIDRequest{UserId: 1})
	if err != nil {
		t.Fatalf("GetUserByID 失败: %v", err)
	}
	if resp.GetUser().GetNickname() == "" {
		t.Fatal("昵称不应为空")
	}
}

go test ./internal/user/grpc/ -run TestGetUserByID -v
# 预期：--- PASS: TestGetUserByID (0.00s)
# 全程不监听任何端口，不需要先启动 webook，也不需要网络

# configs/config.yaml 新增 grpc 段（其余保持不变）
grpc:
  keepalive:
    time: 10s          # 探测间隔
    timeout: 5s        # 等 ACK 超时
  tls:
    enabled: false     # 本地开发关闭；生产置 true
    cert_file: configs/certs/server.crt
    key_file:  configs/certs/server.key

// 文件路径: internal/user/ioc/grpc.go（节选：在原 InitGRPCServer 基础上增加选项）
func InitGRPCServer(v *viper.Viper, l *logger.Logger, svc *usergrpc.UserServiceServer) *grpc.Server {
	opts := []grpc.ServerOption{
		grpc.ChainUnaryInterceptor(traceInterceptor(), logInterceptor(l)), // 顺序：先补全上下文，再打日志
		grpc.KeepaliveParams(keepalive.ServerParameters{
			Time:    v.GetDuration("grpc.keepalive.time"),
			Timeout: v.GetDuration("grpc.keepalive.timeout"),
		}),
		grpc.KeepaliveEnforcementPolicy(keepalive.EnforcementPolicy{
			MinTime:             v.GetDuration("grpc.keepalive.time") / 2, // 客户端探测间隔别小于服务端的一半
			PermitWithoutStream: true,
		}),
	}
	if v.GetBool("grpc.tls.enabled") { // 只有开关打开才启用 TLS
		creds, err := credentials.NewServerTLSFromFile(
			v.GetString("grpc.tls.cert_file"), v.GetString("grpc.tls.key_file"))
		if err != nil {
			panic(err) // 开了 TLS 却读不到证书 = 配置错误，直接失败，绝不"降级成明文"
		}
		opts = append(opts, grpc.Creds(creds))
	}
	s := grpc.NewServer(opts...)
	userv1.RegisterUserServiceServer(s, svc)
	reflection.Register(s)
	return s
}

// cmd/webook/main.go（节选：调用处传入 viper）
grpcSrv := userioc.InitGRPCServer(viper, logger, usergrpc.NewUserServiceServer(userSvc))

// 文件路径: internal/user/ioc/grpc.go（traceId 拦截器）
// traceKey 是 ctx 里存取 traceId 的私有 key（不要用 string 当 key）
type traceKey struct{}

// traceInterceptor：上游带了 x-trace-id 就用上游的；没带就本地生成一个兜底
func traceInterceptor() grpc.UnaryServerInterceptor {
	return func(ctx context.Context, req any, info *grpc.UnaryServerInfo,
		handler grpc.UnaryHandler) (any, error) {
		traceID := "trace-" + strconv.FormatInt(time.Now().UnixNano(), 36)
		if md, ok := metadata.FromIncomingContext(ctx); ok {
			if vals := md.Get("x-trace-id"); len(vals) > 0 {
				traceID = vals[0] // 同一条请求全链路共用一个 ID
			}
		}
		ctx = context.WithValue(ctx, traceKey{}, traceID)
		return handler(ctx, req) // 注意：带着新 ctx 往下走
	}
}

// 文件路径: internal/post/ioc/grpc.go（节选：在原 InitUserConn 基础上按配置决定是否启用 TLS）
func InitUserConn(v *viper.Viper) *grpc.ClientConn {
	var opts []grpc.DialOption
	if v.GetBool("grpc.tls.enabled") {
		creds, err := credentials.NewClientTLSFromFile(v.GetString("grpc.tls.cert_file"), "")
		if err != nil {
			panic(err)
		}
		opts = append(opts, grpc.WithTransportCredentials(creds))
	} else {
		opts = append(opts, grpc.WithTransportCredentials(insecure.NewCredentials()))
	}
	conn, err := grpc.NewClient(v.GetString("user.grpc.addr"), opts...)
	if err != nil {
		panic(err)
	}
	return conn
}

// 文件路径: internal/post/grpc/user_client.go（节选：每次调用附加 traceId）
func (c *GRPCUserClient) GetUserByID(ctx context.Context, id int64) (common.UserBasicInfo, error) {
	ctx, cancel := context.WithTimeout(ctx, 3*time.Second)
	defer cancel()
	// traceId 附加进 metadata：服务端拦截器会取出来写进日志，同一条请求全链路一个 ID
	traceID := "trace-" + strconv.FormatInt(time.Now().UnixNano(), 36) // 生产里用第 08 章的链路追踪 ID
	ctx = metadata.AppendToOutgoingContext(ctx, "x-trace-id", traceID)

	resp, err := c.remote.GetUserByID(ctx, &userv1.GetUserByIDRequest{UserId: id})
	if err != nil {
		return common.UserBasicInfo{}, fmt.Errorf("gRPC 查询用户 %d: %w", id, err)
	}
	u := resp.GetUser()
	return common.UserBasicInfo{Id: u.GetId(), Nickname: u.GetNickname(), Avatar: u.GetAvatar()}, nil
}

go build ./... && go run ./cmd/webook
# 1) 默认配置（tls.enabled=false）：行为与之前一致——curl /api/post/1 正常返回
curl -s http://127.0.0.1:8080/api/post/1
# 预期：{"code":0,...,"author":{...}}；服务端日志里出现 trace_id=trace-xxx（透传生效）

# 2) 演练 TLS：先生成自签证书（命令见 3.20 节），把 grpc.tls.enabled 改为 true 并重启
grpcurl -cacert configs/certs/server.crt -d '{"user_id": 1}' 127.0.0.1:9090 user.v1.UserService/GetUserByID
# 预期：正常返回用户 JSON（这条链路已被 TLS 加密）
# 改回 false 重启即恢复明文——本地开发才这么干，生产必须常开

content-community/
├── api/
│   ├── proto/user|post/v1/       # ★ user.proto / post.proto 接口定义（post 本章只定义）
│   └── gen/user|post/v1/         # ★ 生成代码 4 件套（*.pb.go 与 *_grpc.pb.go，提交 git、禁手改）
├── cmd/webook/main.go            # ▲ 模块组装 + HTTP/gRPC 并行启动
├── configs/
│   ├── config.yaml               # ▲ 新增 user.grpc.addr、post.use_grpc_user 与 grpc.* 段
│   └── certs/                    # ★ 第 8 步：自签证书（本地演练；生产用 CA 签发）
└── internal/
    ├── common/types.go           # ★ UserBasicInfo 共享值对象
    ├── user/                     # ▲ 模块化移入（第 02 章分层代码）
    │   ├── api.go                # ★ UserModule 接口 + 本地实现
    │   ├── grpc/server.go        # ★ gRPC 服务端
    │   ├── grpc/server_test.go   # ★ 第 7 步：bufconn 无网络单测
    │   └── ioc/grpc.go           # ★ Server 初始化 + 日志/traceId 拦截器 + Keepalive/TLS
    ├── post/                     # ▲ 模块化移入
    │   ├── service/post.go       # ▲ 改为依赖 user.UserModule 接口
    │   ├── grpc/user_client.go   # ★ gRPC 客户端（实现 UserModule）
    │   └── ioc/grpc.go           # ★ 连接初始化（viper 读地址）
    ├── interaction/ | rank/ | sms/   # ▲ 第 07/09 章互动、榜单、短信代码整体挪入
    └── notification/             # ★ 预留空目录