以下内容按“最佳实践 + 小型代码示例”的风格，给出一个用 Go 实现的订单微服务，REST 与 gRPC 同时暴露，涵盖分层架构、仓储模式、pgx 连接池与重试、幂等与并发控制、熔断与退避、可观测性（OpenTelemetry/Prometheus/zap）、优雅停机/健康探针、表驱动测试与 testcontainers 等关键点。示例代码尽量精简，能作为最小可运行骨架进行扩展。
一、分层架构与仓储模式（context 贯穿）
- 分层建议：transport(HTTP/gRPC) -> service(业务用例) -> repository(数据访问) -> db。
- 所有公开方法第一个参数使用 context.Context，传播超时、取消、tracing、日志字段等。
- Repository 隔离持久化细节，service 仅关心业务流程；transport 只做编解码、验证、鉴权。
示例领域模型与接口
// internal/domain/order.go
package domain
import "time"
type Order struct {
ID string
DedupKey string // 幂等去重键（外部传入，需唯一约束）
UserID string
AmountCents int64
Status string // created, paid, failed...
Version int64 // 乐观锁版本
CreatedAt time.Time
UpdatedAt time.Time
}
// 仓储接口
type OrderRepository interface {
Create(ctx context.Context, o Order) (Order, error) // 幂等：基于 DedupKey
Get(ctx context.Context, id string) (Order, error)
UpdateStatusOptLock(ctx context.Context, id string, fromVersion int64, newStatus string) (Order, error)
}
二、PostgreSQL（pgx）连接池、超时与重试
- 使用 pgxpool，统一初始化连接池，设置最大连接、生命周期、acquire timeout。
- 在 service 层设置合理的超时（如 200-500ms 查询、1-2s 写入），在 repository 直接使用传入的 ctx。
- 对可重试的瞬时错误（序列化失败 40001、死锁 40P01、连接重置等）做有限次重试 + 指数退避。
示例：pgx 连接与重试
// internal/db/pg.go
package db
import (
"context"
"time"
"errors"
"github.com/cenkalti/backoff/v4"
"github.com/jackc/pgx/v5/pgxpool"
"github.com/jackc/pgx/v5"
"github.com/jackc/pgconn"
)
func NewPool(ctx context.Context, url string) (*pgxpool.Pool, error) {
cfg, err := pgxpool.ParseConfig(url)
if err != nil { return nil, err }
cfg.MaxConns = 20
cfg.MinConns = 2
cfg.MaxConnLifetime = time.Hour
cfg.MaxConnIdleTime = 10 * time.Minute
cfg.HealthCheckPeriod = 30 * time.Second
cfg.ConnConfig.ConnectTimeout = 5 * time.Second
return pgxpool.NewWithConfig(ctx, cfg)
}
func IsRetryablePgErr(err error) bool {
var pgErr *pgconn.PgError
if errors.As(err, &pgErr) {
switch pgErr.Code {
case "40001", "40P01": // serialization_failure, deadlock_detected
return true
}
}
// 网络层或临时 IO
return errors.Is(err, pgx.ErrNoRows) == false && pgconn.SafeToRetry(err)
}
func WithTxRetry(ctx context.Context, pool *pgxpool.Pool, isoLevel pgx.TxIsoLevel, fn func(pgx.Tx) error) error {
bo := backoff.NewExponentialBackOff()
bo.InitialInterval = 20 * time.Millisecond
bo.MaxInterval = 200 * time.Millisecond
bo.MaxElapsedTime = 1 * time.Second
operation := func() error {
tx, err := pool.BeginTx(ctx, pgx.TxOptions{IsoLevel: isoLevel})
if err != nil { return backoff.Permanent(err) }
defer tx.Rollback(ctx)
if err := fn(tx); err != nil {
if IsRetryablePgErr(err) {
return err // 触发 backoff 重试
}
return backoff.Permanent(err)
}
return tx.Commit(ctx)
}
return backoff.Retry(operation, bo)
}
三、幂等设计、去重键与悲观/乐观锁
- 去重键：对外暴露 dedup_key，orders 表建立唯一约束，插入使用 INSERT ... ON CONFLICT。
- 乐观锁：更新时带 version 条件，更新成功返回新版本，否则返回冲突错误。
- 悲观锁：需要串行化修改的行使用 SELECT ... FOR UPDATE/UPDATE ... RETURNING，以及 SKIP LOCKED 支持并发 worker。
- 幂等设计注意：去重键的语义稳定，建立唯一索引；在服务重试或网络抖动下可安全重放。
示例：仓储实现（幂等 + 乐观锁）
// internal/repo/order_repo.go
package repo
import (
"context"
"errors"
"github.com/jackc/pgx/v5"
"github.com/jackc/pgx/v5/pgxpool"
"yourmod/internal/domain"
"yourmod/internal/db"
"time"
)
var ErrConflict = errors.New("conflict")
type OrderRepo struct {
pool *pgxpool.Pool
}
func NewOrderRepo(pool *pgxpool.Pool) *OrderRepo { return &OrderRepo{pool: pool} }
// SQL schema 要有：
// create table orders (
// id uuid primary key default gen_random_uuid(),
// dedup_key text not null unique,
// user_id text not null,
// amount_cents bigint not null,
// status text not null,
// version bigint not null default 1,
// created_at timestamptz not null default now(),
// updated_at timestamptz not null default now()
// );
func (r *OrderRepo) Create(ctx context.Context, o domain.Order) (domain.Order, error) {
var out domain.Order
q := `
insert into orders (dedup_key, user_id, amount_cents, status)
values ($1,$2,$3,'created')
on conflict (dedup_key) do update set updated_at = now()
returning id, dedup_key, user_id, amount_cents, status, version, created_at, updated_at;
`
err := db.WithTxRetry(ctx, r.pool, pgx.Serializable, func(tx pgx.Tx) error {
return tx.QueryRow(ctx, q, o.DedupKey, o.UserID, o.AmountCents).
Scan(&out.ID, &out.DedupKey, &out.UserID, &out.AmountCents, &out.Status, &out.Version, &out.CreatedAt, &out.UpdatedAt)
})
return out, err
}
func (r *OrderRepo) Get(ctx context.Context, id string) (domain.Order, error) {
var o domain.Order
q := `select id, dedup_key, user_id, amount_cents, status, version, created_at, updated_at from orders where id=$1`
err := r.pool.QueryRow(ctx, q, id).Scan(&o.ID, &o.DedupKey, &o.UserID, &o.AmountCents, &o.Status, &o.Version, &o.CreatedAt, &o.UpdatedAt)
return o, err
}
func (r *OrderRepo) UpdateStatusOptLock(ctx context.Context, id string, fromVersion int64, newStatus string) (domain.Order, error) {
var o domain.Order
q := `
update orders
set status=$3, version=version+1, updated_at=now()
where id=$1 and version=$2
returning id, dedup_key, user_id, amount_cents, status, version, created_at, updated_at;
`
cmd, err := r.pool.Query(ctx, q, id, fromVersion, newStatus)
if err != nil { return o, err }
defer cmd.Close()
if !cmd.Next() { return o, ErrConflict }
err = cmd.Scan(&o.ID, &o.DedupKey, &o.UserID, &o.AmountCents, &o.Status, &o.Version, &o.CreatedAt, &o.UpdatedAt)
return o, err
}
// 悲观锁示意（库存/队列工作项）：SELECT ... FOR UPDATE SKIP LOCKED
// tx.Query(ctx, `select id from jobs where status='ready' for update skip locked limit 1`)
四、熔断与回退策略，外部调用重试退避
- 统一外部调用客户端，加入重试（幂等操作）、指数退避、超时；添加熔断器保护下游。
- 回退策略：熔断打开时快速失败并采用降级方案（例如记录待支付任务，异步补偿）。
示例：带熔断与退避的支付客户端
// internal/ext/pay_client.go
package ext
import (
"context"
"errors"
"net/http"
"time"
"github.com/sony/gobreaker"
"github.com/cenkalti/backoff/v4"
"go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp"
)
type PayClient struct {
httpc *http.Client
breaker *gobreaker.CircuitBreaker
}
func NewPayClient() *PayClient {
st := gobreaker.Settings{
Name: "payment",
MaxRequests: 5,
Interval: 30 * time.Second,
Timeout: 10 * time.Second,
ReadyToTrip: func(counts gobreaker.Counts) bool {
return counts.ConsecutiveFailures >= 5
},
}
return &PayClient{
httpc: &http.Client{
Timeout: 2 * time.Second,
Transport: otelhttp.NewTransport(http.DefaultTransport),
},
breaker: gobreaker.NewCircuitBreaker(st),
}
}
func (c *PayClient) Authorize(ctx context.Context, orderID string, amount int64) error {
op := func() error {
_, err := c.breaker.Execute(func() (interface{}, error) {
req, _ := http.NewRequestWithContext(ctx, http.MethodPost, "http://payment/api/authorize", nil)
resp, err := c.httpc.Do(req)
if err != nil { return nil, err }
defer resp.Body.Close()
if resp.StatusCode >= 500 { return nil, errors.New("payment 5xx") }
if resp.StatusCode >= 400 { return nil, backoff.Permanent(errors.New("payment 4xx")) }
return nil, nil
})
return err
}
bo := backoff.WithContext(backoff.NewExponentialBackOff(), ctx)
return backoff.Retry(op, bo)
}
五、OpenTelemetry 分布式追踪、Prometheus 指标与结构化日志（zap）
- 初始化 OTel：OTLP 导出器 -> Collector；HTTP 使用 otelhttp、gRPC 使用 otelgrpc 拦截器自动注入 trace。
- Prometheus：暴露 /metrics，添加自定义业务指标（订单创建计数、延迟直方图等）。
- 日志：zap 生产级 JSON，带 trace_id、span_id、request_id 等；不同层使用 context 传播。
示例：可观测性初始化与采样指标
// internal/observ/otel.go
package observ
import (
"context"
"time"
"go.opentelemetry.io/otel"
"go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp"
sdktrace "go.opentelemetry.io/otel/sdk/trace"
"go.opentelemetry.io/otel/sdk/resource"
"go.opentelemetry.io/otel/propagation"
semconv "go.opentelemetry.io/otel/semconv/v1.21.0"
)
func InitOTel(ctx context.Context, service string) (func(context.Context) error, error) {
exp, err := otlptracehttp.New(ctx) // 读 OTEL_EXPORTER_OTLP_ENDPOINT 等环境变量
if err != nil { return nil, err }
res, _ := resource.New(ctx, resource.WithAttributes(semconv.ServiceName(service)))
tp := sdktrace.NewTracerProvider(
sdktrace.WithBatcher(exp),
sdktrace.WithResource(res),
sdktrace.WithSampler(sdktrace.ParentBased(sdktrace.TraceIDRatioBased(0.2))),
)
otel.SetTracerProvider(tp)
otel.SetTextMapPropagator(propagation.TraceContext{})
return tp.Shutdown, nil
}
// internal/observ/metrics.go
package observ
import "github.com/prometheus/client_golang/prometheus"
var (
OrdersCreated = prometheus.NewCounter(prometheus.CounterOpts{
Name: "orders_created_total", Help: "Total created orders",
})
OrderCreateLatency = prometheus.NewHistogram(prometheus.HistogramOpts{
Name: "order_create_seconds", Help: "Latency of order creation", Buckets: prometheus.DefBuckets,
})
)
func MustRegisterMetrics() {
prometheus.MustRegister(OrdersCreated, OrderCreateLatency)
}
// internal/observ/logging.go
package observ
import (
"go.uber.org/zap"
"context"
"go.opentelemetry.io/otel/trace"
)
func NewLogger() *zap.Logger {
l, _ := zap.NewProduction()
return l
}
func WithTraceFields(ctx context.Context, l *zap.Logger) *zap.Logger {
span := trace.SpanFromContext(ctx)
sc := span.SpanContext()
if sc.HasTraceID() {
l = l.With(zap.String("trace_id", sc.TraceID().String()), zap.String("span_id", sc.SpanID().String()))
}
return l
}
六、服务层与路由（REST 与 gRPC）
- REST 选择 chi/gin，gRPC 使用官方 server，二者共享同一 service。
- HTTP 路由增加 otelhttp 和请求日志中间件；gRPC 加 otelgrpc 拦截器和健康服务。
- 健康检查与就绪探针：/healthz（活性），/readyz（检查 DB Ping）。
proto（最小化）
// api/order/v1/order.proto
syntax = "proto3";
package order.v1;
option go_package = "yourmod/api/order/v1;orderv1";
service OrderService {
rpc CreateOrder(CreateOrderRequest) returns (CreateOrderResponse);
rpc GetOrder(GetOrderRequest) returns (GetOrderResponse);
}
message CreateOrderRequest { string dedup_key = 1; string user_id = 2; int64 amount_cents = 3; }
message CreateOrderResponse { string order_id = 1; }
message GetOrderRequest { string order_id = 1; }
message GetOrderResponse { string order_id = 1; string status = 2; int64 amount_cents = 3; }
service 与 transport 示例
// internal/service/order_service.go
package service
import (
"context"
"time"
"yourmod/internal/domain"
"yourmod/internal/repo"
"yourmod/internal/ext"
"yourmod/internal/observ"
"go.uber.org/zap"
)
type OrderService struct {
repo repo.OrderRepo
pay *ext.PayClient
log *zap.Logger
}
func NewOrderService(r *repo.OrderRepo, p *ext.PayClient, l *zap.Logger) *OrderService {
return &OrderService{repo: *r, pay: p, log: l}
}
func (s *OrderService) Create(ctx context.Context, dedupKey, userID string, amount int64) (domain.Order, error) {
ctx, cancel := context.WithTimeout(ctx, 2*time.Second)
defer cancel()
start := time.Now()
o, err := s.repo.Create(ctx, domain.Order{DedupKey: dedupKey, UserID: userID, AmountCents: amount})
observ.OrderCreateLatency.Observe(time.Since(start).Seconds())
if err != nil { return o, err }
observ.OrdersCreated.Inc()
log := observ.WithTraceFields(ctx, s.log)
// 外部支付授权（演示可选）
if err := s.pay.Authorize(ctx, o.ID, o.AmountCents); err != nil {
log.Warn("payment authorize failed, fallback", zap.Error(err))
// 回退方案：标记待支付状态，或写出补偿消息
}
return o, nil
}
func (s *OrderService) Get(ctx context.Context, id string) (domain.Order, error) {
ctx, cancel := context.WithTimeout(ctx, 500*time.Millisecond)
defer cancel()
return s.repo.Get(ctx, id)
}
// internal/transport/http/router.go
package httpapi
import (
"encoding/json"
"net/http"
"github.com/go-chi/chi/v5"
"go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp"
"yourmod/internal/service"
"yourmod/internal/observ"
"github.com/jackc/pgx/v5/pgxpool"
)
func NewRouter(svc *service.OrderService, pool *pgxpool.Pool) http.Handler {
r := chi.NewRouter()
r.Use(otelhttp.NewMiddleware("http"))
r.Get("/healthz", func(w http.ResponseWriter, r *http.Request) { w.WriteHeader(http.StatusOK) })
r.Get("/readyz", func(w http.ResponseWriter, r *http.Request) {
if err := pool.Ping(r.Context()); err != nil { http.Error(w, "not ready", 503); return }
w.WriteHeader(http.StatusOK)
})
r.Handle("/metrics", promHandler()) // 见下
r.Post("/orders", func(w http.ResponseWriter, r *http.Request) {
var req struct {
DedupKey string `json:"dedup_key"`
UserID string `json:"user_id"`
Amount int64 `json:"amount_cents"`
}
if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
http.Error(w, err.Error(), 400); return
}
o, err := svc.Create(r.Context(), req.DedupKey, req.UserID, req.Amount)
if err != nil { http.Error(w, err.Error(), 500); return }
_ = json.NewEncoder(w).Encode(map[string]string{"order_id": o.ID})
})
r.Get("/orders/{id}", func(w http.ResponseWriter, r *http.Request) {
id := chi.URLParam(r, "id")
o, err := svc.Get(r.Context(), id)
if err != nil { http.Error(w, err.Error(), 404); return }
_ = json.NewEncoder(w).Encode(o)
})
return r
}
func promHandler() http.Handler {
observ.MustRegisterMetrics()
return promhttp.Handler()
}
// internal/transport/grpc/server.go
package grpcapi
import (
"context"
"yourmod/api/order/v1"
"yourmod/internal/service"
"go.opentelemetry.io/contrib/instrumentation/google.golang.org/grpc/otelgrpc"
"google.golang.org/grpc"
"google.golang.org/grpc/health"
healthpb "google.golang.org/grpc/health/grpc_health_v1"
)
type Server struct {
orderv1.UnimplementedOrderServiceServer
svc *service.OrderService
}
func NewServer(s *service.OrderService) *Server { return &Server{svc: s} }
func (s *Server) CreateOrder(ctx context.Context, req *orderv1.CreateOrderRequest) (*orderv1.CreateOrderResponse, error) {
o, err := s.svc.Create(ctx, req.DedupKey, req.UserId, req.AmountCents)
if err != nil { return nil, err }
return &orderv1.CreateOrderResponse{OrderId: o.ID}, nil
}
func (s *Server) GetOrder(ctx context.Context, req *orderv1.GetOrderRequest) (*orderv1.GetOrderResponse, error) {
o, err := s.svc.Get(ctx, req.OrderId)
if err != nil { return nil, err }
return &orderv1.GetOrderResponse{OrderId: o.ID, Status: o.Status, AmountCents: o.AmountCents}, nil
}
func NewGRPCServer(s *service.OrderService) *grpc.Server {
gs := grpc.NewServer(
grpc.UnaryInterceptor(otelgrpc.UnaryServerInterceptor()),
grpc.StreamInterceptor(otelgrpc.StreamServerInterceptor()),
)
orderv1.RegisterOrderServiceServer(gs, NewServer(s))
healthSrv := health.NewServer()
healthpb.RegisterHealthServer(gs, healthSrv)
return gs
}
七、优雅停机、健康检查与就绪探针
- 多 server 并行启动（HTTP、gRPC、metrics），使用 errgroup + context 管理。
- 捕获 SIGINT/SIGTERM，调用 HTTP Server.Shutdown、gRPC GracefulStop、关闭 pg 池。
- K8s：livenessProbe 指向 /healthz；readinessProbe 指向 /readyz；gRPC 可用 grpc-health-probe。
最小可运行 main
// cmd/ordersvc/main.go
package main
import (
"context"
"net"
"net/http"
"os"
"os/signal"
"syscall"
"time"
"golang.org/x/sync/errgroup"
"go.uber.org/zap"
"go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp"
"yourmod/internal/db"
"yourmod/internal/observ"
"yourmod/internal/repo"
"yourmod/internal/service"
httpapi "yourmod/internal/transport/http"
grpcapi "yourmod/internal/transport/grpc"
"yourmod/internal/ext"
)
func main() {
ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM)
defer stop()
log := observ.NewLogger()
defer log.Sync()
shutdownOTel, err := observ.InitOTel(ctx, "ordersvc")
if err != nil { log.Fatal("otel init", zap.Error(err)) }
defer shutdownOTel(context.Background())
pool, err := db.NewPool(ctx, os.Getenv("DATABASE_URL"))
if err != nil { log.Fatal("db", zap.Error(err)) }
defer pool.Close()
pay := NewPayClient()
repo := repo.NewOrderRepo(pool)
svc := service.NewOrderService(repo, pay, log)
httpSrv := &http.Server{
Addr: ":8080",
Handler: httpapi.NewRouter(svc, pool),
ReadHeaderTimeout: 5 * time.Second,
}
grpcSrv := grpcapi.NewGRPCServer(svc)
g, ctx := errgroup.WithContext(ctx)
// HTTP
g.Go(func() error {
log.Info("http listening", zap.String("addr", httpSrv.Addr))
if err := httpSrv.ListenAndServe(); err != nil && err != http.ErrServerClosed { return err }
return nil
})
// gRPC
g.Go(func() error {
lis, err := net.Listen("tcp", ":9090")
if err != nil { return err }
log.Info("grpc listening", zap.String("addr", ":9090"))
return grpcSrv.Serve(lis)
})
// 等待信号
g.Go(func() error {
<-ctx.Done()
c, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()
_ = httpSrv.Shutdown(c)
grpcSrv.GracefulStop()
return nil
})
if err := g.Wait(); err != nil {
log.Error("server exit", zap.Error(err))
}
}
八、表驱动测试与集成测试（testcontainers）
- 表驱动测试：同一用例逻辑，不同输入/预期，代码简洁可读。
- 集成测试：用 testcontainers 启动临时 Postgres，运行 schema/migrations，执行仓储/服务真实调用，保证幂等与事务语义。
表驱动示例
// internal/service/order_service_test.go
package service_test
import (
"context"
"testing"
"yourmod/internal/service"
"yourmod/internal/domain"
)
type stubRepo struct{ created map[string]domain.Order }
func (s *stubRepo) Create(ctx context.Context, o domain.Order) (domain.Order, error) {
if s.created == nil { s.created = map[string]domain.Order{} }
if existing, ok := s.created[o.DedupKey]; ok { return existing, nil }
o.ID = "id-" + o.DedupKey; s.created[o.DedupKey] = o; return o, nil
}
// implement other methods ...
func TestCreate_Idempotent(t *testing.T) {
r := &stubRepo{}
svc := service.NewOrderService((*repo.OrderRepo)(r), nil, zap.NewNop())
ctx := context.Background()
cases := []struct{
dedup string; wantID string
}{
{"k1", "id-k1"},
{"k1", "id-k1"},
}
var first string
for i, c := range cases {
o, err := svc.Create(ctx, c.dedup, "u", 100)
if err != nil { t.Fatal(err) }
if i == 0 { first = o.ID }
if o.ID != first { t.Fatalf("idempotency broken: %s != %s", o.ID, first) }
}
}
testcontainers 集成测试示例（简化）
// internal/repo/order_repo_integration_test.go
package repo_test
import (
"context"
"testing"
"time"
"fmt"
tc "github.com/testcontainers/testcontainers-go"
"github.com/testcontainers/testcontainers-go/wait"
"github.com/jackc/pgx/v5/pgxpool"
"yourmod/internal/db"
"yourmod/internal/repo"
"yourmod/internal/domain"
)
func startPostgres(t *testing.T) (*pgxpool.Pool, func()) {
ctx := context.Background()
req := tc.ContainerRequest{
Image: "postgres:16-alpine",
Env: map[string]string{"POSTGRES_PASSWORD": "pw", "POSTGRES_DB":"test"},
ExposedPorts: []string{"5432/tcp"},
WaitingFor: wait.ForListeningPort("5432/tcp").WithStartupTimeout(30*time.Second),
}
pgC, err := tc.GenericContainer(ctx, tc.GenericContainerRequest{ContainerRequest: req, Started: true})
if err != nil { t.Fatal(err) }
host, _ := pgC.Host(ctx)
port, _ := pgC.MappedPort(ctx, "5432/tcp")
url := fmt.Sprintf("postgres://postgres:pw@%s:%s/test?sslmode=disable", host, port.Port())
pool, err := db.NewPool(ctx, url)
if err != nil { t.Fatal(err) }
schema := `
create extension if not exists pgcrypto;
create table if not exists orders(
id uuid primary key default gen_random_uuid(),
dedup_key text not null unique,
user_id text not null,
amount_cents bigint not null,
status text not null,
version bigint not null default 1,
created_at timestamptz not null default now(),
updated_at timestamptz not null default now()
);`
if _, err := pool.Exec(ctx, schema); err != nil { t.Fatal(err) }
cleanup := func() {
pool.Close()
_ = pgC.Terminate(ctx)
}
return pool, cleanup
}
func TestRepo_Create_Idempotent(t *testing.T) {
pool, cleanup := startPostgres(t)
defer cleanup()
r := repo.NewOrderRepo(pool)
ctx := context.Background()
o1, err := r.Create(ctx, domain.Order{DedupKey: "d1", UserID:"u1", AmountCents: 100})
if err != nil { t.Fatal(err) }
o2, err := r.Create(ctx, domain.Order{DedupKey: "d1", UserID:"u1", AmountCents: 100})
if err != nil { t.Fatal(err) }
if o1.ID != o2.ID { t.Fatalf("expect same id, got %s vs %s", o1.ID, o2.ID) }
}
九、Makefile 与容器化建议
- Makefile 目标：build/test/run/lint/proto/docker-build。
- Dockerfile：多阶段构建，非 root 用户，最小基础镜像（distroless/alpine），设置健康检查，合理暴露端口（HTTP 8080，gRPC 9090，/metrics 同 HTTP）。
- 通过环境变量配置：DATABASE_URL、OTEL_EXPORTER_OTLP_ENDPOINT、LOG_LEVEL 等。
Makefile（简化）
APP=ordersvc
PKG=./...
BIN=./bin/$(APP)
build:
go build -o $(BIN) ./cmd/ordersvc
test:
go test $(PKG) -count=1
run:
DATABASE_URL=postgres://user:pw@localhost:5432/db?sslmode=disable go run ./cmd/ordersvc
proto:
protoc --go_out=. --go-grpc_out=. api/order/v1/*.proto
docker-build:
docker build -t $(APP):latest .
Dockerfile（简化）
# build
FROM golang:1.22 AS builder
WORKDIR /src
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -o /out/ordersvc ./cmd/ordersvc
# runtime
FROM gcr.io/distroless/base-debian12
USER nonroot:nonroot
WORKDIR /app
COPY --from=builder /out/ordersvc /app/ordersvc
EXPOSE 8080 9090
ENV GODEBUG=madvdontneed=1
ENTRYPOINT ["/app/ordersvc"]
K8s 探针建议
- livenessProbe HTTP GET /healthz，periodSeconds: 10, timeoutSeconds: 2。
- readinessProbe HTTP GET /readyz，initialDelaySeconds: 5，failureThreshold: 3。
- gRPC 使用 grpc-health-probe 亦可。
十、其他实践建议
- 输入校验：REST 使用 binding/validator，gRPC 使用 protoc-gen-validate。
- 安全与合规：限制请求体大小、超时、最大并发（HTTP Server Read/Write Timeout，gRPC keepalive）、对外调用限流（token bucket）。
- 迁移工具：goose 或 golang-migrate，CI 中执行迁移。
- 配置管理：viper/envconfig，支持多环境；敏感信息用 Secret。
- 性能与池化：避免全局变量污染，复用 http.Client、连接池；对热点路径加缓存（带过期与一致性策略）。
- 灰度与回滚：版本化 API，兼容旧客户端；数据库变更遵循 expand/contract。
只要将以上骨架按模块放入 yourmod 项目中，即可得到一个最小可运行、可观测、可测试、可容器化的 Go 订单微服务，并可逐步扩展业务逻辑与非功能性需求。
