./
├── Readme.md
├── api/
│   ├── book/
│   │   └── v1/
│   │       └── book.proto
│   └── common/
│       └── v1/
│           └── types.proto
├── buf.gen.yaml
├── buf.lock
├── buf.yaml
├── cmd/
│   ├── client/
│   │   └── book/
│   └── server/
│       └── book/
│           └── main.go
├── config/
│   └── config.yml
├── go.mod
├── go.sum
├── internal/
│   ├── client/
│   │   └── book/
│   │       └── client.go
│   ├── pkg/
│   │   ├── config/
│   │   │   ├── config.go
│   │   │   └── viper.go
│   │   ├── database/
│   │   │   └── gorm.go
│   │   ├── logger/
│   │   │   ├── context.go
│   │   │   └── logger.go
│   │   └── otel/
│   │       └── otel.go
│   └── server/
│       ├── book/
│       │   ├── model/
│       │   │   ├── biz/
│       │   │   │   └── book.go
│       │   │   └── db/
│       │   │       └── book.go
│       │   ├── repo/
│       │   │   ├── book.go
│       │   │   └── converter.go
│       │   ├── server/
│       │   │   ├── di.go
│       │   │   └── server.go
│       │   ├── service/
│       │   │   ├── book.go
│       │   │   └── converter.go
│       │   └── usecase/
│       │       └── book.go
│       └── common/
│           └── interceptor/
│               ├── initialize.go
│               ├── logger.go
│               └── validator.go
└── util/
    └── file/
        └── file.go

version: v2
managed:
  enabled: true
  override:
    - file_option: go_package
      path: book/v1
      value: bookstore/api/book/v1;bookv1
    - file_option: go_package
      path: common/v1
      value: bookstore/api/common/v1;commonv1
plugins:
  - remote: buf.build/protocolbuffers/go
    out: api
    opt:
      - paths=source_relative
  - remote: buf.build/grpc/go
    out: api
    opt:
      - paths=source_relative
inputs:
  - directory: api

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

package book.v1;

import "common/v1/types.proto";
import "google/protobuf/field_mask.proto";
import "google/protobuf/struct.proto";
import "google/protobuf/timestamp.proto";

option go_package = "bookstore/api/book/v1;bookv1";

service BookService {
  rpc GetBook(GetBookRequest) returns (GetBookResponse);
  rpc CreateBook(CreateBookRequest) returns (CreateBookResponse);
  rpc ListBooks(ListBooksRequest) returns (ListBooksResponse);
  rpc UpdateBook(UpdateBookRequest) returns (UpdateBookResponse);
  rpc DeleteBook(DeleteBookRequest) returns (DeleteBookResponse);
}

message GetBookRequest {
  int64 id = 1;
}

message GetBookResponse {
  common.v1.Book book = 1;
}

message CreateBookRequest {
  common.v1.Book book = 1;
}

message CreateBookResponse {
  common.v1.Book book = 1;
}

message ListBooksRequest {
  int32 page_number = 1;
  int32 page_size = 2;
  repeated common.v1.OrderBy order_by = 3;
  map<string, google.protobuf.Value> filter = 4;
}

message ListBooksResponse {
  repeated common.v1.Book books = 1;
  int32 total_count = 2;
  int32 page_number = 3;
  int32 page_size = 4;
}

message UpdateBookRequest {
  common.v1.Book book = 1;
  google.protobuf.FieldMask update_mask = 2;
}

message UpdateBookResponse {
  common.v1.Book book = 1;
}

message DeleteBookRequest {
  int64 id = 1;
}

message DeleteBookResponse {
  int64 id = 1;
  google.protobuf.Timestamp deleted_at = 2;
}

// api/common/v1/types.proto
syntax = "proto3";

package common.v1;

import "google/protobuf/timestamp.proto";

option go_package = "bookstore/api/common/v1;commonv1";

enum BookStatus {
  BOOK_STATUS_UNSPECIFIED = 0;
  BOOK_STATUS_AVAILABLE = 1; // 可用
  BOOK_STATUS_UNAVAILABLE = 2; // 不可用
  BOOK_STATUS_BORROWED = 3; // 借出
  BOOK_STATUS_LOST = 4; // 丢失
  BOOK_STATUS_RESERVED = 6; // 预约
}

message Book {
  int64 id = 1;
  BookStatus status = 2;
  google.protobuf.Timestamp created_at = 3;
  google.protobuf.Timestamp updated_at = 4;
  google.protobuf.Timestamp deleted_at = 5;
  string title = 6;
  string author = 7;
  double price = 8;
  string isbn = 9;
  string publisher = 10;
  google.protobuf.Timestamp published_at = 11;
}

message OrderBy {
  string field = 1;
  bool ascending = 2;
}

// internal/server/book/service/book.go
type BookService struct {
  bookv1.UnimplementedBookServiceServer
  bu *usecase.BookUsecase
}

func NewBookService(bu *usecase.BookUsecase) *BookService {
  return &BookService{bu: bu}
}

func (s *BookService) GetBook(ctx context.Context, req *bookv1.GetBookRequest) (*bookv1.GetBookResponse, error) {
  bizBook, err := s.bu.GetBook(ctx, req.Id)
  if err != nil {
    return nil, status.Errorf(codes.Internal, "failed to get book: %v", err)
  }

  return &bookv1.GetBookResponse{Book: BizToV1Book(bizBook)}, nil
}

func (s *BookService) CreateBook(ctx context.Context, req *bookv1.CreateBookRequest) (*bookv1.CreateBookResponse, error) {
  // ...
}

func (s *BookService) ListBooks(ctx context.Context, req *bookv1.ListBooksRequest) (*bookv1.ListBooksResponse, error) {
  // ...
}

func (s *BookService) UpdateBook(ctx context.Context, req *bookv1.UpdateBookRequest) (*bookv1.UpdateBookResponse, error) {
  // ...
}

func (s *BookService) DeleteBook(ctx context.Context, req *bookv1.DeleteBookRequest) (*bookv1.DeleteBookResponse, error) {
  // ...
}

// internal/server/book/server/server.go
type BookServer struct {
  port int
}

func NewBookServer(port int) *BookServer {
  return &BookServer{port: port}
}

func (s *BookServer) Run(ctx context.Context) error {

  lis, err := net.Listen("tcp", fmt.Sprintf(":%d", s.port))
  if err != nil {
    return fmt.Errorf("failed to listen: %w", err)
  }
  defer lis.Close()

  grpcServer := grpc.NewServer()
  bookv1.RegisterBookServiceServer(grpcServer, BuildBookService())

  go func() {
    <-ctx.Done()
    log.Println("shutting down server...")
    grpcServer.GracefulStop()
  }()

  log.Printf("server listening at port %d", s.port)
  if err := grpcServer.Serve(lis); err != nil {
    if err == grpc.ErrServerStopped {
      log.Println("server stopped")
      return nil
    }
    return fmt.Errorf("failed to serve: %w", err)
  }
  return nil
}

func BuildBookService() *service.BookService {
  br := repo.NewBookRepository()
  bu := usecase.NewBookUsecase(br)
  return service.NewBookService(bu)
}

$ grpcurl -plaintext localhost:8081 describe book.v1.BookService
book.v1.BookService is a service:
service BookService {
  rpc CreateBook ( .book.v1.CreateBookRequest ) returns ( .book.v1.CreateBookResponse );
  rpc DeleteBook ( .book.v1.DeleteBookRequest ) returns ( .book.v1.DeleteBookResponse );
  rpc GetBook ( .book.v1.GetBookRequest ) returns ( .book.v1.GetBookResponse );
  rpc ListBooks ( .book.v1.ListBooksRequest ) returns ( .book.v1.ListBooksResponse );
  rpc UpdateBook ( .book.v1.UpdateBookRequest ) returns ( .book.v1.UpdateBookResponse );
}

$ grpcurl -plaintext localhost:8081 describe book.v1.BookService.GetBook
book.v1.BookService.GetBook is a method:
rpc GetBook ( .book.v1.GetBookRequest ) returns ( .book.v1.GetBookResponse );

$ grpcurl -plaintext localhost:8081 describe .book.v1.GetBookResponse                           
book.v1.GetBookResponse is a message:
message GetBookResponse {
  .common.v1.Book book = 1;
}

$ grpcurl -plaintext localhost:8081 describe .common.v1.Book
common.v1.Book is a message:
message Book {
  int64 id = 1;
  .common.v1.BookStatus status = 2;
  .google.protobuf.Timestamp created_at = 3;
  .google.protobuf.Timestamp updated_at = 4;
  .google.protobuf.Timestamp deleted_at = 5;
  string title = 6;
  string author = 7;
  double price = 8;
  string isbn = 9;
  string publisher = 10;
  .google.protobuf.Timestamp published_at = 11;
}

$ grpcurl -plaintext -d '{"id":1}' localhost:8081 book.v1.BookService/GetBook
{
  "book": {
    "id": "1",
    "title": "The Great Gatsby",
    "author": "F. Scott Fitzgerald",
    "price": 10.99,
    "isbn": "978-0-7432-1967-1",
    "publisher": "Scribner",
    "publishedAt": "2026-04-16T01:47:46.470161300Z"
  }
}

# linux
$ grpcurl -plaintext -d @ localhost:8081 book.v1.BookService/GetBook <<EOM
{"id": 1}
EOM
{
  "book": {
    "id": "1",
    "title": "The Great Gatsby",
    "author": "F. Scott Fitzgerald",
    "price": 10.99,
    "isbn": "978-0-7432-1967-1",
    "publisher": "Scribner",
    "publishedAt": "2026-04-16T01:47:11.511262700Z"
  }
}

// internal/client/book/client.go
type Client struct {
  bookv1.BookServiceClient
  conn *grpc.ClientConn
}

func NewClient(host string, port int) (*Client, error) {
  serverAddr := fmt.Sprintf("%s:%d", host, port)

  opts := []grpc.DialOption{
    grpc.WithTransportCredentials(insecure.NewCredentials()),
  }
  conn, err := grpc.NewClient(serverAddr, opts...)
  if err != nil {
    return nil, fmt.Errorf("failed to create client: %w", err)
  }
  return &Client{
    BookServiceClient: bookv1.NewBookServiceClient(conn),
    conn:              conn,
  }, nil
}

func (c *Client) Close() error {
  return c.conn.Close()
}

func (c *Client) GetBook(ctx context.Context, id int64) (*commonv1.Book, error) {
  resp, err := c.BookServiceClient.GetBook(ctx, &bookv1.GetBookRequest{Id: id})
  if err != nil {
    return nil, fmt.Errorf("failed to get book: %w", err)
  }
  return resp.Book, nil
}

// ...

service BookService {
  rpc GetBook(GetBookRequest) returns (GetBookResponse);
  rpc CreateBook(CreateBookRequest) returns (CreateBookResponse);
  rpc ListBooks(ListBooksRequest) returns (ListBooksResponse);
  rpc UpdateBook(UpdateBookRequest) returns (UpdateBookResponse);
  rpc DeleteBook(DeleteBookRequest) returns (DeleteBookResponse);
  // new
  rpc BatchImportBooks(stream BatchImportBooksRequest) returns (BatchImportBooksResponse);
  rpc BatchExportBooks(BatchExportBooksRequest) returns (stream BatchExportBooksResponse);
  rpc HeartBeat(stream HeartBeatRequest) returns (stream HeartBeatResponse);
}


message BatchImportBooksRequest {
  common.v1.Book book = 1;
}

message BatchImportBooksResponse {
  int32 total = 1;
  int32 success = 2;
  repeated string error_messages = 3;
}

message BatchExportBooksRequest {
  repeated int64 book_ids = 1;
}

message BatchExportBooksResponse {
  int64 book_id = 1;
  common.v1.Book book = 2;
  string error_message = 3;
}

message HeartBeatRequest {
  // 1: ping, 2: pong
  common.v1.HeartBeatType type = 1;
  int64 sent_at = 2;
}

message HeartBeatResponse {
  // 1: ping, 2: pong
  common.v1.HeartBeatType type = 1;
  int64 sent_at = 2;
  int64 received_at = 3;
}

enum HeartBeatType {
  HEART_BEAT_TYPE_UNSPECIFIED = 0;
  HEART_BEAT_TYPE_PING = 1; // 心跳请求
  HEART_BEAT_TYPE_PONG = 2; // 心跳响应
}

func (s *BookService) BatchImportBooks(stream bookv1.BookService_BatchImportBooksServer) error {
  var total int32
  var success int32
  var errorMessages []string
  for {
    req, err := stream.Recv()
    if err == io.EOF {
      break
    }
    if err != nil {
      return status.Errorf(codes.Internal, "failed to receive request: %v", err)
    }
    bizBook := V1ToBizBook(req.Book)
    _, err = s.bu.CreateBook(stream.Context(), bizBook)
    if err != nil {
      errorMessages = append(errorMessages, fmt.Sprintf("failed to create book %s: %v", bizBook.Title, err))
    } else {
      success++
    }
    total++

  }
  return stream.SendAndClose(&bookv1.BatchImportBooksResponse{
    Total:         total,
    Success:       success,
    ErrorMessages: errorMessages,
  })
}

func (s *BookService) HeartBeat(stream bookv1.BookService_HeartBeatServer) error {
  sendCh := make(chan *bookv1.HeartBeatResponse, 10)
  done := make(chan struct{})
  defer close(done)

  // 发送消息到客户端
  sender := func() {
    for {
      select {
      case msg, ok := <-sendCh:
        if !ok {
          return
        }
        if err := stream.Send(msg); err != nil {
          log.Printf("failed to send message: %v", err)
          return
        }
        log.Println("sent message:", msg.Type)
      case <-done:
        log.Println("sender goroutine stopped")
        return
      case <-stream.Context().Done():
        log.Println("client disconnected, stopping sender goroutine")
        return
      }
    }
  }

  // 定时发送心跳消息
  ticker := func() {
    jitter := time.Duration(rand.Intn(10)) * time.Second
    ticker := time.NewTicker(1*time.Minute + jitter)
    defer ticker.Stop()

    for {
      select {
      case <-ticker.C:
        sendCh <- &bookv1.HeartBeatResponse{
          Type:   commonv1.HeartBeatType_HEART_BEAT_TYPE_PING,
          SentAt: time.Now().UnixMilli(),
        }
      case <-done:
        log.Println("ticker goroutine stopped")
        return
      case <-stream.Context().Done():
        log.Println("client disconnected, stopping ticker goroutine")
        return
      }
    }
  }

  // 接收客户端的心跳消息
  receiver := func() error {
    for {
      req, err := stream.Recv()
      if err == io.EOF {
        break
      }
      if err != nil {
        return status.Errorf(codes.Internal, "failed to receive request: %v", err)
      }

      switch req.Type {
      case commonv1.HeartBeatType_HEART_BEAT_TYPE_PING:
        sendCh <- &bookv1.HeartBeatResponse{
          Type:   commonv1.HeartBeatType_HEART_BEAT_TYPE_PONG,
          SentAt: req.SentAt,
        }
      case commonv1.HeartBeatType_HEART_BEAT_TYPE_PONG:
        receivedAt := time.Now().UnixMilli()
        log.Println("received pong, latency:", receivedAt-req.SentAt)
      default:
        log.Println("received unknown heart beat type")
        return status.Errorf(codes.InvalidArgument, "unknown heart beat type: %v", req.Type)
      }
    }
    return nil
  }

  go ticker()
  go sender()
  return receiver()
}

func (c *Client) BatchExportBooks(ctx context.Context, bookIds []int64) ([]*commonv1.Book, []string, error) {
  req := &bookv1.BatchExportBooksRequest{BookIds: bookIds}
  stream, err := c.BookServiceClient.BatchExportBooks(ctx, req)
  if err != nil {
    return nil, nil, fmt.Errorf("failed to export books: %w", err)
  }

  books := make([]*commonv1.Book, 0)
  errorMessages := make([]string, 0)
  for {
    resp, err := stream.Recv()
    if err == io.EOF {
      break
    }
    if err != nil {
      return nil, nil, fmt.Errorf("failed to receive response: %w", err)
    }
    if resp.ErrorMessage != "" {
      errorMessages = append(errorMessages, fmt.Sprintf("failed to export book with ID %d: %s", resp.BookId, resp.ErrorMessage))
      continue
    }
    books = append(books, resp.Book)
  }
  return books, errorMessages, nil
}

func (c *Client) HeartBeat(ctx context.Context) error {
  stream, err := c.BookServiceClient.HeartBeat(ctx)
  if err != nil {
    return fmt.Errorf("failed to create heart beat stream: %w", err)
  }

  sendCh := make(chan *bookv1.HeartBeatRequest, 10)
  done := make(chan struct{})
  defer close(done)

  // 发送消息到服务端
  sender := func() {
    for {
      select {
      case msg, ok := <-sendCh:
        if !ok {
          return
        }
        if err := stream.Send(msg); err != nil {
          log.Printf("failed to send message: %v", err)
          return
        }
        log.Println("sent message:", msg.Type)
      case <-done:
        log.Println("sender goroutine stopped")
        return
      case <-stream.Context().Done():
        log.Println("client disconnected, stopping sender goroutine")
        return
      }
    }
  }

  // 定时发送心跳消息
  ticker := func() {
    jitter := time.Duration(rand.Intn(10)) * time.Second
    ticker := time.NewTicker(1*time.Minute + jitter)
    defer ticker.Stop()

    for {
      select {
      case <-ticker.C:
        sendCh <- &bookv1.HeartBeatRequest{
          Type:   commonv1.HeartBeatType_HEART_BEAT_TYPE_PING,
          SentAt: time.Now().UnixMilli(),
        }
      case <-done:
        log.Println("ticker goroutine stopped")
        return
      case <-stream.Context().Done():
        log.Println("client disconnected, stopping ticker goroutine")
        return
      }
    }
  }

  // 接收服务端的心跳消息
  receiver := func() error {
    for {
      req, err := stream.Recv()
      if err == io.EOF {
        break
      }
      if err != nil {
        return status.Errorf(codes.Internal, "failed to receive request: %v", err)
      }

      switch req.Type {
      case commonv1.HeartBeatType_HEART_BEAT_TYPE_PING:
        sendCh <- &bookv1.HeartBeatRequest{
          Type:   commonv1.HeartBeatType_HEART_BEAT_TYPE_PONG,
          SentAt: req.SentAt,
        }
      case commonv1.HeartBeatType_HEART_BEAT_TYPE_PONG:
        receivedAt := time.Now().UnixMilli()
        log.Println("received pong, latency:", receivedAt-req.SentAt)
      default:
        log.Println("received unknown heart beat type")
        return status.Errorf(codes.InvalidArgument, "unknown heart beat type: %v", req.Type)
      }
    }
    return nil
  }

  go ticker()
  go sender()
  return receiver()
}

message GetBookRequest {
  int64 id = 1 [(buf.validate.field).int64.gte = 1];
}

message CreateBookRequest {
  common.v1.Book book = 1 [(buf.validate.field).cel = {
    id: "create_book.required_fields"
    message: "title and author are required"
    expression:
      "this.title != ''"
      "&& this.author != ''"
  }];
}

message ListBooksRequest {
  optional int32 page_number = 1 [(buf.validate.field).int32.gte = 1];
  optional int32 page_size = 2 [(buf.validate.field).int32.gte = 1];
  repeated common.v1.OrderBy order_by = 3;
  map<string, google.protobuf.Value> filter = 4;
}

message UpdateBookRequest {
  common.v1.Book book = 1 [(buf.validate.field).cel = {
    id: "update_book.required_fields"
    message: "id is required"
    expression: "this.id > 0"
  }];
  google.protobuf.FieldMask update_mask = 2;
}