server

package module
v1.4.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 20, 2026 License: Apache-2.0 Imports: 0 Imported by: 0

README

server

server 是个人使用的 Go 服务基础类库,模块路径为 github.com/go-sdk/server。项目使用 gmux 在同一个端口提供原生 gRPC 和 grpc-gateway HTTP API,通过 core/lifex 管理进程生命周期,并统一请求上下文、访问日志、Payload Logging、JWT 鉴权、Protovalidate、Health、Recovery、TLS 和优雅停止行为。

环境要求

  • Go 1.27 或更高版本

安装

go get github.com/go-sdk/server

公共 Protobuf

buf.build/go-sdk/server 公共模块同时包含 server.common 通用类型和 server.options 自定义选项。业务协议可以直接引用:

import "common/common.proto";
import "options/options.proto";

message ListUserReq {
  server.common.Paging paging = 1;
}

server.common 提供单个和批量标识、资源元数据、动态属性、分页和时间范围,并通过 public import 传递常用 Google Protobuf 类型。TimeRange 在首尾时间都存在时要求开始时间不得晚于结束时间。

Go 代码使用仓库内生成包,以便同时获得手写辅助方法:

import "github.com/go-sdk/server/common"

paging := common.NewPaging(2, 20)
offset, limit := paging.GetOffsetLimit()
responsePaging := paging.WithTotal(100)

NewPaging 使用与分页计算方法相同的默认值构造 Paging:页码非正数时按第 1 页处理,每页数量非正数时使用 common.DefaultLimit。GetOffsetLimit、GetOffset 和 GetLimit 对手动构造的 Paging 也使用相同规则;WithTotal 返回新的分页对象,不修改原请求。BSR 自动生成的 Go SDK 不包含 common/common.go 中的手写方法;需要这些方法的 Go 项目应依赖 github.com/go-sdk/server/common。

master CI 会持续将根模块中 includes 声明的公共 Proto 发布到 buf.build/go-sdk/server 的 master label,tag CI 则发布对应版本 label;未命名的测试模块不会发布。后续增加公共 Proto 目录时,需要同步将该目录加入 buf.yaml 的 includes。

服务模型

业务接口以 Protobuf gRPC 服务为唯一来源,通过 google.api.http 注解生成 HTTP API。Gateway 使用生成的 Register*HandlerFromEndpoint 回连同端口的真实 gRPC Server,因此 HTTP 和原生 gRPC 请求经过相同的 gRPC interceptor。

上传、下载或 Webhook 等不适合建模为 RPC 的接口,可以通过 Server.HandlePath 直接注册到内部 Gateway Mux。底层 runtime.ServeMux、http.Server 和 grpc.Server 不对外暴露。

HTTP 返回结构

Gateway 成功响应统一将 Protobuf 消息放在 data 下。成功码为零并默认隐藏:

{
  "data": {
    "id": "1"
  }
}

失败响应保留 gRPC code、message 和结构化 details,并增加业务错误码 domain 和本地化文案 reason。details 固定为最后一个字段,未包含结构化详情时输出空数组:

{
  "code": 5,
  "message": "resource not found",
  "domain": "1000002",
  "reason": "文件 report.pdf 不存在",
  "details": []
}

业务错误码通过枚举定义。枚举数字值写入 domain,message 是英文默认文案;http_status 只覆盖 HandlePath 的 HTTP 状态码:

enum ErrorCode {
  ERROR_CODE_UNSPECIFIED = 0;
  ERROR_CODE_FILE_NOT_FOUND = 1000002 [
    (server.options.enum_value).http_status = 404,
    (server.options.enum_value).message = "file {{.Name}} not found"
  ];
}

业务代码以不可变的 standard.Err* 为基座,通过 WithErrorCode 绑定错误码,WithData 提供文案模板变量:

return nil, standard.ErrNotFound.
	WithErrorCode(common.ErrorCode_ERROR_CODE_FILE_NOT_FOUND).
	WithData(map[string]any{"Name": "report.pdf"})

默认语言是英文。Server 根据 HTTP Accept-Language 或 gRPC accept-language metadata 选择翻译;目标语言不存在时回退到枚举 option 中的英文 message,英文文案缺失或模板渲染失败(包括缺少 WithData 提供的模板变量)时回退到枚举名称。reason 是最终渲染结果,domain 是枚举数字值的十进制字符串。两者通过 google.rpc.ErrorInfo 在 gRPC 中传递,Gateway 会提升到失败响应顶层,不在 details 中重复输出。

推荐由业务服务使用 TOML 文件维护翻译,并通过 embed.FS 注入。Server 自动以英文创建 Bundle、注册 TOML 解析器并递归加载全部 .toml 文件;翻译消息 ID 使用 domain 的数字字符串。例如 locales/zh-CN.toml:

["1000001"]
other = "无效的文件名"

["1000002"]
other = "文件 {{.Name}} 不存在"

业务入口只需嵌入语言目录:

//go:embed locales/*.toml
var localeFS embed.FS

server, err := standard.New(
	standard.WithI18nFS(localeFS),
	// ...
)

语言标签从文件名读取,支持 zh-CN.toml 或 active.zh-CN.toml。没有 TOML 文件、文件名语言标签无效或内容解析失败时,standard.New 直接返回错误。英文默认文案继续来自错误码的 message option,不要求提供 en.toml。需要自行配置其他格式或复数规则时,可以继续使用 WithI18nBundle 注入完整 Bundle。

优先使用 ErrInternal、ErrInvalidParam、ErrUnauthenticated、ErrNotFound、ErrPermissionDenied、ErrAlreadyExists、ErrResourceExhausted、ErrFailedPrecondition、ErrAborted 和 ErrUnavailable 等不可变的内置错误模板;只有缺少对应模板时才使用 standard.NewError(code, message)。WithMessage、WithErrorCode、WithData、WithDomainReason、WithDetails 和 WithHTTPStatus 都返回副本,可以安全地复用错误模板。WithDomainReason 保留给不使用错误码枚举的业务。WithHTTPStatus 不改变原生 gRPC Code。

数据库、缓存或第三方 SDK 的错误可以通过 ErrorConverter 统一转换,而不让 Server 直接依赖具体驱动:

standard.WithErrorConverters(
	standard.ErrorConvertFunc(func(err error) (standard.RespError, bool) {
		switch {
		case errors.Is(err, sql.ErrNoRows):
			return standard.ErrNotFound.WithMessage("record not found").
				WithDomainReason("RECORD_NOT_FOUND", "record.not_found"), true
		case errors.Is(err, gorm.ErrRecordNotFound):
			return standard.ErrNotFound.WithMessage("record not found").
				WithDomainReason("RECORD_NOT_FOUND", "record.not_found"), true
		default:
			return standard.RespError{}, false
		}
	}),
)

转换器按注入顺序执行,第一个返回 true 的结果生效;未匹配错误保持不变。转换同时覆盖 unary 和 stream RPC,应用可以使用 errors.Is 或 errors.As 识别被包装的依赖错误。

创建服务

userService := NewUserService()

server, err := standard.New(
	standard.WithName("user-service"),
	standard.WithAddress(":8080"),
	standard.WithJWTSecret([]byte(os.Getenv("JWT_SECRET"))),
	standard.WithReflection(),
	standard.WithGRPCRegister(
		func(registrar grpc.ServiceRegistrar) {
			corev1.RegisterUserServiceServer(registrar, userService)
		},
	),
	standard.WithGatewayRegister(
		corev1.RegisterUserServiceHandlerFromEndpoint,
	),
)
if err != nil {
	return err
}

多个服务可以在同一个 Option 中注册:

standard.WithGRPCRegister(
	func(registrar grpc.ServiceRegistrar) {
		corev1.RegisterUserServiceServer(registrar, userService)
	},
	func(registrar grpc.ServiceRegistrar) {
		bizv1.RegisterBillServiceServer(registrar, billService)
	},
)

standard.WithGatewayRegister(
	corev1.RegisterUserServiceHandlerFromEndpoint,
	bizv1.RegisterBillServiceHandlerFromEndpoint,
)

不要使用生成代码中的 Register*HandlerServer,该方式会直接调用业务实现并绕过 gRPC interceptor。

额外 HTTP 接口

err = server.HandlePath(
	http.MethodPost,
	"/upload",
	func(c *standard.Context) error {
		if _, _, err := c.ReadFormFile("file", 32<<20); err != nil {
			return err
		}
		return c.NoContent(http.StatusNoContent)
	},
)

HandlePath 接收 standard.HandlerFunc,其签名为 func(c *standard.Context) error,并且只能在 Start 前调用。Handler 返回 nil 表示响应已经正常完成;返回 RespError 时,Server 会按照与 Gateway 相同的 code、message、domain、reason 和 details 结构写入响应,并根据 gRPC Code 设置 HTTP 状态码。已注册的 Error Converter 同样作用于额外 HTTP Handler;未匹配的普通错误不会向调用方暴露原始信息,而是返回 ErrInternal。如果响应体已经开始写入,后续返回的错误只会记录日志,不会覆盖已提交的响应。

Context 通过 Request 和 Response 暴露原始 *http.Request 与 http.ResponseWriter,同时提供 Param、Query、Queries、Header、FormValue、FormFile、ReadFormFile、SetHeader、JSON、Text、Blob 和 NoContent 等常用辅助方法。ReadFormFile(name, maxFileBytes) 分别限制文件内容和包含固定表单开销的请求体,使用受控的内存阈值解析 multipart 表单,并负责关闭文件及清理临时文件;请求或文件超限返回 HTTP 413 和 ErrResourceExhausted,表单或字段无效返回 ErrInvalidParam。NewHTTPContext 可用于不启动 Server 的 Handler 单元测试。

额外 HTTP 接口会经过 HTTP 链路标识(TraceID/SpanID)、访问日志和 Recovery,但没有 protobuf 消息,因此不会应用 Protovalidate。

配置 JWT 后,额外 HTTP 接口同样要求 Authorization: Bearer <token>,并可直接通过 c.JWT() 读取已验证的 Claims 和请求参数。鉴权失败和 Handler panic 也使用统一错误结构。额外接口没有 Protobuf MethodOptions,不能使用 skip_auth。

示例接口测试

tests/docs/api.http 提供可由 JetBrains HTTP Client 执行的示例接口测试,覆盖 Gateway 的创建、参数校验和分页响应,以及额外 HTTP 路由的上传、下载、鉴权和错误文案本地化。运行前启动 tests/server,并选择 tests/docs/http-client.env.json 中的 local 环境。

local.token 仅用于本仓库示例服务,由与 tests/server/main.go 相同的测试密钥 12345678 签发。修改示例服务的 JWT 密钥时必须同步更新该 Token。上传和下载共享示例服务进程内的文件存储,因此下载成功用例需要先执行“上传文件”;重启服务后也需要重新上传。Protobuf 的零值字段默认不输出,分页用例只断言请求中实际指定的页码和每页数量。

启动与停止

if err := lifex.Init(); err != nil {
	lifex.Shutdown(err)
}
if err := lifex.Wait(); err != nil {
	return err
}

New 会将 Server 的 Start 和 Stop 注册到全局 lifex。lifex.Init 完成监听和 Gateway 注册后异步启动服务;lifex.Wait 阻塞等待 SIGINT、SIGTERM 或 lifex.Shutdown。服务异常退出时,错误会通过 lifex.Shutdown 传递给 Wait。配置 WithName 后,启动、停止日志会增加 server 字段,HTTP 或 gRPC Serve 异常也会包含该实例名称;该名称不会写入请求 metadata,也不会修改 core/logx 的进程级全局字段。

也可以由业务逻辑主动触发退出:

lifex.Shutdown(reason)

lifex.Wait 会逆序执行全部解构函数。Server 的 Stop 会并行排空 HTTP 与 gRPC 请求,并使用 WithGracefulTimeout 配置的超时完成优雅停止,默认五秒;Server 只能启动一次,Stop 可以重复调用。

TLS

server, err := standard.New(
	standard.WithAddress(":8443"),
	standard.WithCertificate("server.crt", "server.key"),
	standard.WithGatewayServerName("api.example.com"),
	// 其他服务注册 Options。
)

也可以直接注入内存中的 PEM 内容:

server, err := standard.New(
	standard.WithAddress(":8443"),
	standard.WithCertificatePEM(certPEM, keyPEM),
	standard.WithGatewayServerName("api.example.com"),
	// 其他服务注册 Options。
)

证书和私钥必须同时指定。Gateway 默认使用注入的证书文件或证书 PEM 作为回连 gRPC 的信任根,并使用真实 endpoint 主机名进行校验;监听通配地址或证书名称不同时,应通过 WithGatewayServerName 指定证书名称。

复杂 TLS、动态证书和 mTLS 可以使用 WithTLSConfig。如果 Gateway 需要独立的客户端 TLS 策略,可通过 WithGatewayDialOptions 覆盖默认传输凭据;不得使用跳过证书校验作为生产默认配置。

Options

Option 用途
WithName 设置生命周期日志和 Serve 异常中的 Server 实例标识
WithAddress 设置监听地址,默认 :8080
WithListener 注入 Listener,优先于 Address
WithGracefulTimeout 设置 lifex 解构阶段的停止超时,默认五秒
WithCertificate 设置 TLS 证书和私钥文件
WithCertificatePEM 设置内存中的 PEM 证书和私钥
WithTLSConfig 注入自定义 TLS 配置
WithGatewayEndpoint 为非 TCP Listener 或特殊网络覆盖 Gateway endpoint
WithGatewayServerName 设置 Gateway TLS 回连校验名称
WithGatewayDialOptions 追加或覆盖 Gateway gRPC 客户端配置
WithGatewayOptions 注入 grpc-gateway Mux Options
WithGRPCServerOptions 注入 gRPC Server Options
WithHTTPServerOptions 调整 HTTP Server 超时等参数,Handler 不允许替换
WithUnaryInterceptors 在标准校验和 Recovery 之间插入 unary interceptor
WithStreamInterceptors 在标准校验和 Recovery 之间插入 stream interceptor
WithErrorConverters 将数据库等应用依赖错误转换为 RespError
WithI18nFS 从 embed.FS 递归加载 TOML 错误文案
WithI18nBundle 注入业务错误文案的 go-i18n 翻译目录
WithGRPCRegister 注册真实 gRPC 服务
WithGatewayRegister 注册 google.api.http 生成的 Gateway endpoint
WithLogger 替换默认的 core/logx gRPC 日志适配器
WithJWTSecret 注入 HS256 密钥并启用 JWT 鉴权
WithJWTAuth 注入自定义 jwtx.Parser,支持非对称算法和外部密钥源
WithReflection 启用标准 gRPC Reflection Service

默认 Middleware

gRPC interceptor 顺序为:

Request Context -> Logging -> Payload Logging -> JWT Auth -> Protovalidate -> 自定义 Interceptor -> Error Converter -> Recovery
  • Request Context 对外使用 X-Request-Id 请求头和 gRPC x-request-id metadata 接收与回写链路标识;内部统一命名为 TraceID(standard.TraceIDKey,日志字段 trace-id),缺失时生成 UUID v7,并在同一进程内透传。每次请求进入服务时生成新的 SpanID(standard.SpanIDKey,日志字段 span-id),标识本服务内单次请求到响应的处理,不向下游透传,也不出现在任何响应中。TraceID、SpanID、调用深度、客户端 IP、content-type、user-agent 和原始 Accept-Language 会写入 standard.Context,语言偏好还会透传给下游 gRPC 服务。
  • core/logx.Ctx(ctx) 自动携带 trace-id、span-id 和 depth;业务代码通过 standard.FromContext(ctx) 读取请求参数和 JWT Claims。
  • Logging 记录协议、方法、状态和耗时;Payload Logging 分别输出 grpc request 和 grpc response,不记录认证头、JWT 原文或完整 metadata。
  • Payload Logging 的 content_length 是 proto.Size 得到的逻辑消息长度,不代表压缩和 HTTP/2 帧编码后的网络字节数。
  • 方法设置 (server.options.method).skip_log = true 时仍记录请求与响应元数据,但 payload 使用 ***;字段设置 (server.options.field).sensitive = true 时递归脱敏。
  • 配置 WithJWTSecret 后使用 HS256 验证 Bearer Token,WithJWTAuth 可注入非对称算法和外部密钥源的 jwtx.Parser;方法设置 (server.options.method).skip_auth = true 时跳过鉴权。
  • Protovalidate 执行 Protobuf 中的 buf.validate 规则,失败时返回 InvalidArgument。
  • Error Converter 按注册顺序将应用依赖错误转换为统一 RespError;额外 HTTP Handler 的未匹配错误统一隐藏为 ErrInternal。
  • Recovery 将 gRPC panic 转换为 Internal,额外 HTTP Handler 的 panic 转换为统一 ErrInternal 响应。

请求上下文

requestContext := standard.FromContext(ctx)
traceID := requestContext.TraceID()
spanID := requestContext.SpanID()
clientIP := requestContext.ClientIP()
depth := requestContext.Depth()
claims := requestContext.JWT()
acceptLanguage := requestContext.AcceptLanguage()

TraceID 是跨服务透传的链路标识,对外线上协议固定为 X-Request-Id 请求头和 gRPC x-request-id metadata;SpanID 由每个服务在请求入口生成,只标识本服务内这一次请求到响应的处理,仅随日志输出,不随出站调用传递,也不写入 HTTP 响应头或 gRPC 响应 metadata。HTTP 响应只会写一个 X-Request-Id;Gateway 不透传任何 gRPC 响应头,因此 HTTP 响应中不会出现 Grpc-Metadata- 前缀的头或重复的 X-Request-Id。

JWT() 返回已验证 Claims 的副本,不包含原始 Bearer Token;JWTClaims(target) 将 Claims 解码到自定义结构,用于业务侧读取强类型声明。未配置鉴权 Option 时不启用鉴权。标准 gRPC Health Service 始终启用,并固定跳过鉴权和 Payload Logging;Reflection 默认关闭,仅通过 WithReflection() 启用,启用后仍遵循 JWT 鉴权。

JWT 的签发和解析统一由 github.com/go-sdk/server/jwtx 提供:jwtx.Signer 以指定算法和密钥签发 token,jwtx.Parser 按算法白名单和密钥函数解析,jwtx.Codec 内嵌两者同时提供签发和解析。jwtx.HS256(secret) 返回对称密钥 Codec,jwtx.Ed25519(privateKeyPEM) 从 PEM 编码的 PKCS#8 私钥构造私钥签发、对应公钥解析的 Codec;仅需解析时直接使用 codec.Parser。jwtx.Claims 提供 jti/sub/iat/exp 四个标准声明字段(时间为 jwtx.Time,payload 内使用秒级时间戳),其余声明与标准声明同级扁平存放在 Extra 并可通过 Decode 解码到目标结构;jwtx.MapClaims 与服务端中间件写入上下文的声明类型一致。

需要为主动发起的调用补充请求参数时,使用 standard.NewContext:

ctx = standard.NewContext(ctx,
	standard.TraceIDKey, traceID,
	standard.DepthKey, depth,
)

gRPC Client

conn, err := standard.NewClient("dns:///user-service:8080")
if err != nil {
	return err
}
client := corev1.NewUserServiceClient(conn)

Client 默认使用明文连接,并由 lifex 在解构阶段关闭。默认 interceptor 负责 Logging、Payload Logging,以及从 standard.Context 透传 x-request-id metadata、已验证 JWT 对应的 Bearer Token,并将 x-depth 加一。SpanID 不透传,由下游服务在请求入口自行生成。认证原文不会通过公共 Context API 暴露或写入日志。

通过根证书文件、根证书 PEM 或完整 TLS 配置启用 TLS:

conn, err := standard.NewClient(
	"dns:///user-service:8443",
	standard.WithClientRootCertificatePEM(rootCertPEM),
	standard.WithClientServerName("user-service.example.com"),
)

可用的 Client Options 包括 WithClientTLSConfig、WithClientRootCertificate、WithClientRootCertificatePEM、WithClientServerName、WithClientDialOptions、WithClientUnaryInterceptors、WithClientStreamInterceptors 和 WithClientLogger。

单元测试

standard/testserver 使用 bufconn 启动真实标准 Server,并提供经过默认 Client interceptor 的连接。测试会自动释放 ClientConn、Server 和 Listener:

server := testserver.New(t,
	standard.WithGRPCRegister(func(registrar grpc.ServiceRegistrar) {
		corev1.RegisterUserServiceServer(registrar, &userService{})
	}),
)
client := corev1.NewUserServiceClient(server.Conn())

response, err := client.Health(context.Background(), &common.Empty{})

testserver 固定注入 bufconn Listener,适用于原生 gRPC 和 interceptor 单元测试。需要真实 TCP endpoint 的 grpc-gateway HTTP 路由应使用独立的集成测试。

额外 HTTP Handler 可以使用 NewHTTP 在本地回环端口走完整的标准 HTTP 链路:

server := testserver.NewHTTP(t, http.MethodPost, "/files", uploadHandler,
	standard.WithErrorConverters(databaseErrorConverter),
)
request, err := http.NewRequest(http.MethodPost, server.URL("/files"), body)
if err != nil {
	t.Fatal(err)
}
response, err := server.Client().Do(request)
if err != nil {
	t.Fatal(err)
}
defer response.Body.Close()

NewHTTP 只负责注册一个 HandlePath Handler、启动 Server 并管理 HTTP Client 和资源清理,不初始化应用配置、数据库或迁移。普通 grpc-gateway 生成路由仍应通过对应 Service 的测试覆盖,涉及真实外部依赖时使用独立的集成测试。

开发约定

修改代码前先阅读 AGENTS.md、PROJECT_MAP.md 和本文件。未经明确授权,不运行测试、示例服务或任何真实外部调用。

make run 会先构建并直接启动示例二进制;make build 会先创建 bin 目录,再生成 bin/server。

Documentation

Overview

Package server 是个人使用的 Go 服务基础类库,使用 gmux 在同一个端口提供 原生 gRPC 和 grpc-gateway HTTP API,并统一请求上下文、访问日志、JWT 鉴权、 Protovalidate、Health、Recovery、TLS 和优雅停止行为。

根包本身不提供 API,主要能力位于以下子包:

standard  标准单端口 gRPC/Gateway Server、Client 和测试服务器
common    跨服务公共 Protobuf 类型和 Go 辅助方法
options   服务、方法和字段级的 Protobuf 自定义选项

安装:

go get github.com/go-sdk/server

服务创建、HTTP 返回结构、middleware 顺序和 gRPC Client 等详细说明 见项目 README。

Directories

Path Synopsis
Package common 提供跨服务复用的 Protobuf 类型及其 Go 辅助方法。
Package common 提供跨服务复用的 Protobuf 类型及其 Go 辅助方法。
Package jwtx 提供与传输无关的 JWT 签发和解析, 供 server 鉴权中间件和应用侧共用同一套语义。
Package jwtx 提供与传输无关的 JWT 签发和解析, 供 server 鉴权中间件和应用侧共用同一套语义。
testserver
Package testserver 提供标准 gRPC 与额外 HTTP 接口的测试环境。
Package testserver 提供标准 gRPC 与额外 HTTP 接口的测试环境。
tests
pb/biz/v1
Package bizv1 is a reverse proxy.
Package bizv1 is a reverse proxy.
pb/core/v1
Package corev1 is a reverse proxy.
Package corev1 is a reverse proxy.
server command

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL