极简 Authentication & Authorization

它解决什么问题

ApiHug 把权限定义拆成两部分：

契约层定义：在 proto 中声明资源、权限与授权规则
运行时实现：在 Spring 应用里解析 JWT、装配 Customer、执行权限检查

这样做的好处是，接口契约、权限文档、运行时校验都来自同一份定义。

第一步：定义权限枚举

Protobuf

enum BookAuthorityEnum {
  option (hope.swagger.enm) = {
    description: "Authority used in book project";
  };

  BOOK_ADD = 0 [(hope.constant.field) = {
    code: 1,
    message: "book:add",
    message2: "Authority to add book"
  }];
  BOOK_DELETE = 1 [(hope.constant.field) = {
    code: 2,
    message: "book:delete",
    message2: "Authority to delete book"
  }];
  BOOK_MODIFY = 2 [(hope.constant.field) = {
    code: 3,
    message: "book:modify",
    message2: "Authority to modify book"
  }];
}

第二步：把权限枚举接入 wire 配置

JSON

"authority": {
  "enumClass": "com.novel.book.proto.infra.settings.BookAuthorityEnum",
  "codePrefix": 10240000
}

第三步：在 API 上声明授权规则

Protobuf

rpc ListCategory (CategoryListRequest) returns (CategoryVoResponse) {
  option (hope.swagger.operation) = {
    get: "/list-category";
    description: "List all supported categories";
    priority: MIDDLE;
    output_repeated: true;
    authorization: {
      rbac: {
        authorities: ["BOOK_DELETE"];
        combinator: OR;
        predefined_role_checker: PLATFORM_MANAGER;
      }
    };
  };
}

这里要注意两点：

使用 output_repeated，不要继续使用已废弃的 out_plural
authorities 是列表，应该写成 ["BOOK_DELETE"]，而不是单个字符串

第四步：在应用侧补运行时实现

生成代码通常会在 ${PKG}.infra.security 下提供这些入口：

AnonymousBookCustomer
BookCustomer
BookJWTPicker
BookQuickCustomerRoleChecker
BookSecurityCustomerContextCustomizer
BookSecurityCustomizer

它们的职责通常是：

类型	作用
`*Customer`	当前登录用户对象
`*JWTPicker`	从 Header / Cookie / Session 中提取 Token
`*QuickCustomerRoleChecker`	平台 / 租户等预定义角色校验
`*SecurityCustomerContextCustomizer`	从 Token 或其他来源补充用户上下文
`*SecurityCustomizer`	自定义全局安全策略

第五步：组织你的权限模型

最常见的方式仍然是 RBAC。

例如：

Text

BOOK_ADD: book:add
BOOK_DELETE: book:delete
USER_BLOCK: user:block
USER_EDIT: user:edit
ORDER_APPROVE: order:approve
ORDER_DELETE: order:delete
ORDER_MODIFY: order:modify

这会自然形成稳定的权限层次：

Text

book
  add
  delete
user
  block
  edit
order
  approve
  delete
  modify

与 Spring Security 的关系

这里不建议再写“禁用 Spring Security”的指导。ApiHug Security 本身就是建立在 Spring Security 之上的扩展，正确做法通常是：

让 ApiHug Security 与 Spring Security 一起工作
用 proto + runtime 代码把业务权限接起来
仅在你明确知道自己要裁剪哪些 Spring Security 能力时，再做定制化调整

如果你需要运行时细节，请继续阅读：

ApiHug Spring Security Extension

参考

RBAC - Role-based access control