ApiHug Spring Security Extension

它是什么

it-common-spring-security 是 ApiHug 的 JWT 安全扩展。它建立在 Spring Security OAuth2 JOSE 之上，负责 Token 编解码、请求过滤、Customer 上下文注入，以及与 ApiHug SecurityContext 的运行时授权校验整合。

ApiHug Security 不是替代 Spring Security，而是在 Spring Security 之上做了 ApiHug 风格的契约驱动安全封装。

运行时模型

请求进入应用后，大致流程如下：

过滤器提取 JWT
JwtDecoder 解析 Token
JwtCustomizer 将 Claims 转为业务 Customer
HopeContextHolder 保存当前安全上下文
SecurityAspect 在进入 API 业务方法前执行权限检查
HopeSecurityManager 从 SecurityContext 解析当前方法对应的授权规则
根据角色、权限、内部资源限制等规则决定是否放行

这也是为什么 ApiHug 的 proto 授权定义会在运行时真正生效，而不仅仅是文档或注解提示。

核心组件

`JwtCustomizer`

业务侧实现 JwtCustomizer，负责：

生成 JWT
解析 JWT
将 Claims 填充为具体 Customer
定义匿名用户对象

`HopeSecurityManager`

HopeSecurityManager 是运行时授权入口。它会从 SecurityContext 读取当前 API 方法的授权配置，并结合 Customer、请求上下文、内部资源访问规则完成校验。

`SecurityAspect`

SecurityAspect 是进入业务方法前的切面检查点。ApiHug 的权限校验默认在这里发生。

`InternalResourceAccessChecker`

内部资源检查器根据请求来源头（默认 x-hope-source）区分外部请求与内部调用，防止外部流量访问被标记为 internal 的接口。

`SpringSecurityExceptionHandler`

框架内置了 SpringSecurityExceptionHandler，将常见 Spring Security 异常映射为统一的 ApiHug 错误响应，例如：

AccessDeniedException
AuthenticationCredentialsNotFoundException
BadCredentialsException
UsernameNotFoundException

配置

配置前缀是 hope.security。

配置项	默认值	说明
`hope.security.enable`	`true`	是否启用安全模块
`hope.security.default-access-style`	`DENY`	未配置资源时的默认访问策略
`hope.security.request-origin-header`	`x-hope-source`	请求来源头
`hope.security.external-origin-value`	`external`	外部请求标记值
`hope.security.bypass-origin-check`	`false`	是否跳过来源检查
`hope.security.jwt.secret`	内置默认值	JWT 密钥，生产环境必须替换
`hope.security.jwt.base64-secret`	-	Base64 密钥，优先级高于 `secret`
`hope.security.jwt.token-validity-in-seconds`	`604800`	普通 Token 有效期
`hope.security.jwt.token-validity-in-seconds-for-remember-me`	`2592000`	remember-me Token 有效期

示例：

YAML

hope:
  security:
    enable: true
    default-access-style: DENY
    bypass-origin-check: false
    jwt:
      base64-secret: "your-base64-secret"
      token-validity-in-seconds: 86400

与 Spring Security 的关系

ApiHug Security 会直接注册 JwtDecoder、JwtEncoder、安全过滤器以及异常处理能力，因此它本身就是基于 Spring Security 生态的扩展方案。

因此这里的正确建议是：

不要把 ApiHug Security 描述成“与 Spring Security 不兼容”
不要把“删除 spring-boot-starter-security”当成默认做法
只有在你明确知道自己不需要 Spring Security 相关能力时，才讨论自定义裁剪

对绝大多数 ApiHug 项目，正确方向是让 ApiHug 的安全扩展与 Spring Security 一起工作，而不是强行把 Spring Security 从项目里拆掉。

你通常需要做什么

在 proto 中定义授权规则
生成 wire / runtime 元数据
实现自己的 JwtCustomizer
在业务侧补充 Customer、角色、权限映射
根据项目需要扩展 SecurityCustomizer 或上下文初始化逻辑

如果你还没有定义 proto 授权，请先阅读：

极简 Authentication & Authorization

参考

it-common-spring-plus/it-common-spring-security/README.md
hope.common.spring.security.AbstractSecurityConfiguration
hope.common.spring.security.HopeSecurityManager
hope.common.spring.problem.handler.SpringSecurityExceptionHandler

它是什么

运行时模型

核心组件

JwtCustomizer

HopeSecurityManager

SecurityAspect

InternalResourceAccessChecker

SpringSecurityExceptionHandler

配置