gRPCGo gRPC契约认证授权与权限测试 - 第2节

2.1 Protobuf 语法基础与核心概念

Protocol Buffers（简称 Protobuf）是 gRPC 的接口定义语言（IDL）与序列化协议。在 gRPC-Go 中，所有服务契约、请求与响应结构均由 .proto 文件定义。掌握 Protobuf 语法是构建安全、可验证的 gRPC 服务的第一步。

2.1.1 语法版本与文件结构

每个 .proto 文件必须以 syntax 声明开头，指定使用的 Protobuf 版本。gRPC 推荐使用 proto3，它简化了语法并移除了 required 和 optional（proto3 中所有字段均为可选，但可通过特定语法模拟）。

syntax = "proto3";  // 必须为文件第一行非注释内容

package user.service.v1;  // 包名，用于避免命名冲突

import "google/protobuf/timestamp.proto";  // 导入其他 proto 文件

option go_package = "github.com/example/protos/gen/go/user/v1";  // Go 代码生成路径

2.1.2 Message 定义与字段类型

message 是 Protobuf 的核心结构，对应 Go 中的 struct。每个 message 包含若干字段，每个字段由 类型、字段名 和 字段编号 组成。

message User {
  string user_id = 1;       // 字符串类型，字段编号 1
  string email = 2;         // 字段编号 2
  int32 age = 3;            // 整数类型
  bool is_verified = 4;     // 布尔类型
  Role role = 5;            // 枚举类型
  repeated string tags = 6; // 重复字段（列表）
  map<string, string> metadata = 7; // 映射类型
}

2.2 字段编号：契约的“指纹”

每个字段必须有一个唯一的 字段编号（field number），范围是 1 到 2^29-1（536,870,911）。字段编号在二进制编码中标识字段，一旦发布，不可修改。修改编号会导致旧数据无法解析，破坏契约兼容性。

• 1 ~ 15：占用 1 字节编码，用于频繁出现的字段。
• 16 ~ 2047：占用 2 字节编码，用于较少出现的字段。
• 19000 ~ 19999：保留编号，Protobuf 内部使用，禁止自定义。
• 最大 2^29-1：不推荐使用过大编号，会浪费编码空间。

message UserProfile {
  string display_name = 1;   // 高频字段，使用小编号
  string avatar_url = 2;
  int64 login_count = 16;    // 低频字段，使用较小编号
  string last_ip = 17;
  // 错误示例：不要使用 19000-19999
  // string reserved_field = 19000; // 编译错误
}

2.3 Import 与 Package：模块化契约

大型项目中，.proto 文件需要拆分到不同包和目录。Protobuf 通过 import 和 package 实现模块化。

2.3.1 Package 声明

package 用于防止不同模块中的 message 命名冲突。在 gRPC 中，package 也影响服务方法的全限定名。

// file: auth/v1/auth.proto
syntax = "proto3";
package auth.v1;
option go_package = "github.com/example/protos/gen/go/auth/v1";

message LoginRequest {
  string username = 1;
  string password = 2;
}

message LoginResponse {
  string token = 1;
  int64 expires_at = 2;
}

2.3.2 Import 其他 Proto 文件

使用 import 引用其他 .proto 文件中定义的 message 或 enum。路径相对于 protoc 的 -I 参数指定的搜索路径。

// file: user/v1/user.proto
syntax = "proto3";
package user.v1;
option go_package = "github.com/example/protos/gen/go/user/v1";

import "auth/v1/auth.proto";  // 导入 auth 包中的 message
import "google/protobuf/timestamp.proto";  // 导入官方时间戳

message CreateUserRequest {
  string name = 1;
  auth.v1.LoginRequest login_info = 2;  // 使用导入的 message
  google.protobuf.Timestamp created_at = 3;
}

2.4 完整 Message 定义示例：权限验证上下文

以下示例展示了一个包含权限验证字段的完整 message 定义，结合了枚举、嵌套 message、repeated 和 map。

syntax = "proto3";
package permission.v1;
option go_package = "github.com/example/protos/gen/go/permission/v1";

import "google/protobuf/timestamp.proto";

// 权限动作枚举
enum Action {
  ACTION_UNSPECIFIED = 0;
  ACTION_READ = 1;
  ACTION_WRITE = 2;
  ACTION_DELETE = 3;
  ACTION_ADMIN = 4;
}

// 资源标识
message Resource {
  string type = 1;   // 如 "document", "user", "project"
  string id = 2;     // 资源唯一 ID
  map<string, string> attributes = 3; // 资源属性，用于细粒度权限判断
}

// 权限检查请求
message CheckPermissionRequest {
  string subject_id = 1;           // 用户/角色 ID
  Resource resource = 2;           // 目标资源
  Action action = 3;               // 请求的动作
  repeated string context_tags = 4; // 上下文标签，如 ["ip:192.168.1.1", "time:office_hours"]
  google.protobuf.Timestamp request_time = 5; // 请求时间，用于时间窗口验证
}

// 权限检查响应
message CheckPermissionResponse {
  bool allowed = 1;                // 是否允许
  string reason = 2;               // 拒绝原因（仅当 allowed=false 时）
  int32 evaluation_ms = 3;         // 评估耗时，用于性能监控
}

2.5 Protobuf 编译与 Go 代码生成

编写完 .proto 文件后，需要使用 protoc 编译器生成 Go 代码。以下是标准命令：

protoc --proto_path=. \
       --go_out=. \
       --go_opt=paths=source_relative \
       permission/v1/permission.proto

• --proto_path：指定 proto 文件搜索根目录。
• --go_out：Go 代码输出目录。
• --go_opt=paths=source_relative：生成的 Go 文件路径与 proto 文件路径保持一致。

生成的 Go 代码结构如下：

// 生成的 Go 文件：permission/v1/permission.pb.go
package permissionv1

type Action int32
const (
    Action_ACTION_UNSPECIFIED Action = 0
    Action_ACTION_READ        Action = 1
    Action_ACTION_WRITE       Action = 2
    Action_ACTION_DELETE      Action = 3
    Action_ACTION_ADMIN       Action = 4
)

type Resource struct {
    Type       string            `protobuf:"bytes,1,opt,name=type,proto3" json:"type,omitempty"`
    Id         string            `protobuf:"bytes,2,opt,name=id,proto3" json:"id,omitempty"`
    Attributes map[string]string `protobuf:"bytes,3,rep,name=attributes,proto3" json:"attributes,omitempty" protobuf_key:"bytes,1,opt,name=key,proto3" protobuf_val:"bytes,2,opt,name=value,proto3"`
    // ...
}

type CheckPermissionRequest struct {
    SubjectId    string                 `protobuf:"bytes,1,opt,name=subject_id,json=subjectId,proto3" json:"subject_id,omitempty"`
    Resource     *Resource              `protobuf:"bytes,2,opt,name=resource,proto3" json:"resource,omitempty"`
    Action       Action                 `protobuf:"varint,3,opt,name=action,proto3,enum=permission.v1.Action" json:"action,omitempty"`
    ContextTags  []string               `protobuf:"bytes,4,rep,name=context_tags,json=contextTags,proto3" json:"context_tags,omitempty"`
    RequestTime  *timestamppb.Timestamp `protobuf:"bytes,5,opt,name=request_time,json=requestTime,proto3" json:"request_time,omitempty"`
    // ...
}

2.6 本章小结：Protobuf 契约与权限验证的关联

Protobuf 的 message 定义、字段编号、import/package 机制，直接决定了 gRPC 权限验证的可行性与安全性：

• 字段编号的稳定性：一旦发布，不可修改。权限验证逻辑依赖的字段（如 user_id、role）必须使用固定编号，否则旧客户端或缓存数据会导致验证失败。
• Package 与 Import：将权限相关的 message（如 Token、Permission）放在独立包中，通过 import 复用。这避免了不同服务间权限契约的重复定义和同步问题。
• 枚举与 oneof：使用枚举定义权限动作（如 READ、WRITE），使用 oneof 处理多类型资源，使权限验证逻辑更清晰、类型安全。
• Go 代码生成：生成的 Go 结构体直接用于拦截器中的权限检查，无需手动解析 JSON 或 XML，减少解析错误和安全漏洞。