Spring Boot 3 接入 MaxKey 实战：OIDC 登录、用户信息与单点注销

> 本文对比四个免费候选：两个产品型 IdP（Keycloak、MaxKey），两个框架型方案（Sa-Token、Spring Authorization Server）。四个都是 Apache 2.0，都能私有化，但“装完能用”的程度和 License 之外的成本完全不同。

你的项目是 Spring Boot，这一点决定了判断方式：**产品型 IdP 只要支持标准 OIDC，Spring 侧接法基本一致；框架型方案则要自己补认证服务和用户体系**。所以先看运维成本和开发量，再看许可证。

版本信息查证于 2026-10-25：Keycloak 26.8.1（2026-10-13）、MaxKey 4.2.0（2026-10-21）、Sa-Token 1.46.0（2026-08-19）、Spring Authorization Server 1.5.8（2026-06-09，独立版最后一个版本，后续并入 Spring Security 7）。上线前请以官方页面为准。



## 一分钟结论

| 你的首要诉求 | 推荐 | 理由 |
|---|---|---|
| 最稳、生态最大、长期维护 | **Keycloak** | Apache 2.0，26.8.1，Spring 资料最多，发现文档完整 |
| 中文管理后台、CAS/SAML/SCIM 多协议 | **MaxKey** | Apache 2.0，4.2.0，国产化场景覆盖更全 |
| 团队小、没人愿意维护多套中间件 | **Keycloak** | 单服务 + 数据库即可，组件比 MaxKey 少 |
| 已有 LDAP/AD、要中文账号生命周期管理 | **MaxKey** | 组织架构、同步、审计是它的强项 |
| 只想让 Spring Boot 少改代码 | **Keycloak** | `issuer-uri` 配完就能跑，角色和注销都有现成能力 |
| 只有 2～5 个内部 Java 系统，只求登录态共享 | **Sa-Token** | Apache 2.0，接入最简，但走自有 ticket 协议，不是标准 IdP |
| 有用户中心，要把认证能力做进产品 | **Spring Authorization Server** | Apache 2.0，标准 OIDC，登录页/用户管理/审计全自研 |

**产品型 IdP 里只选一个：Keycloak。**  
**中文后台是硬指标、或必须兼容 CAS/SAML 存量系统：MaxKey，但先做 POC。**  
**只服务几个内部 Java 系统：Sa-Token 比上面两个都轻。**  
**要把认证产品化：Spring Authorization Server。**

---

## 0. 先判断：你真的需要 SSO 吗

SSO（Single Sign-On，单点登录）解决的是**认证集中**的问题，不是权限问题。

出现下面任意一种情况，才值得引入：

- 有 2 个及以上系统，且使用同一批用户；
- 有非 Java 系统、移动端或第三方系统需要接入你的用户体系；
- 需要通过 LDAP / AD / 企业微信 / 钉钉统一登录；
- 有等保、审计、统一密码策略、MFA 等要求。

如果只有一个系统，或者几个系统用户完全不重叠，直接 Spring Security 表单登录就够了。**为了两个内部系统上一套 IdP，通常是过度设计**；只是要共享登录态的话，第 4 节的 Sa-Token 更合适。

还有一个常见误区：SSO 只负责“你是谁”，不负责“你能干什么”。每个业务系统仍然需要自己的权限模型，不要把全部业务权限都塞进认证中心。

---

## 1. 两个产品型 IdP 的基本盘

| 维度 | Keycloak 26.8.1 | MaxKey 4.2.0 |
|---|---|---|
| 许可证 | Apache 2.0 | Apache 2.0 |
| 技术栈 | Java / Quarkus | Java / Spring + Tomcat |
| 运行依赖 | 数据库（PostgreSQL 为主） | JDK 21+、MySQL 8.4+、Redis、Tomcat |
| 协议 | OIDC / OAuth2 / SAML 2.0 | OIDC / OAuth2 / SAML 2.0 / CAS / JWT / SCIM 2.0 |
| 管理后台 | 英文为主，可装中文语言包 | 原生中文 |
| 部署形态 | 认证服务 + 数据库 | 认证端、管理端、两个前端 + 数据库 + 缓存 |
| 生态与资料 | 最多 | 明显较少 |
| 适合的团队 | 想要标准、稳定、资料多 | 国内环境、多协议存量系统 |

两个都不是“轻量工具”，而是完整的 IAM 平台。选它们意味着你愿意承担一套基础设施的运维。

---

## 2. “免费”到底免费到什么程度

这是选型里最容易被含糊过去的一段，尤其在国内语境下，“免费”经常和“社区版”“企业版”“信创版”混在一起。

### 2.1 Keycloak：Apache 2.0，上游功能完整

- 官方仓库采用 Apache 2.0，可商用、可修改、可私有化，保留版权与许可声明即可；
- **功能没有按版本切割**：OIDC、SAML、身份代理、用户联邦、MFA、授权服务都在上游版本里；
- 红帽提供的构建版、技术支持、订阅服务是另一条商业线，属于“要不要买服务”，不是“买不买功能”；
- 因此 Keycloak 的“免费”最干脆：License 不花钱，花的是运维钱。

### 2.2 MaxKey：Apache 2.0 社区版，企业版主要卖服务

- 官方仓库同样采用 Apache 2.0，可商用，要求保留原始版权声明；
- 官网的社区版/企业版对比页给出的口径是：**核心功能模块一致，企业版增加的是专属支持、集成咨询、培训、定制开发、界面定制、紧急故障修复等**；
- 也就是说，MaxKey 更像“开源软件 + 商业服务”，而不是“免费版缺功能”；
- 但涉及**国密算法、等保合规材料、特定行业适配**时，官方页面没有逐项列清，采购前务必让厂商书面确认哪些在社区版、哪些需要企业版或定制；
- 不要因为 GitHub 上是 Apache 2.0，就默认所有交付物（文档、合规材料、连接器）都免费。

### 2.3 四个候选共同的隐性成本

- **基础设施**：数据库、缓存、TLS 证书、备份、监控、日志、负载均衡；
- **高可用**：多实例要共享数据库/缓存，密钥和会话要统一管理；
- **人力**：升级、CVE 补丁、账号问题、登录故障的 on-call；
- **开发量**：框架型方案没有管理台，用户、登录页、审计都得自己写；
- **迁移**：选标准 OIDC 迁移成本低；选私有 ticket 方案基本等于重做；
- **安全**：IdP 是最高价值攻击目标，管理台必须限制来源、开 MFA、独立网络、定期备份签名密钥。

一句话：**免费的是 License，不是运维，也不是开发。**

### 2.4 两个框架型项目：免费，但买的是一套库

- **Sa-Token**：Apache 2.0，v1.46.0，没有社区版/企业版之分，也没有付费功能墙；项目接受赞助，但功能不按付费切割；
- **Spring Authorization Server**：Apache 2.0，同样没有付费功能墙；可选的商业支持是订阅服务，不买也能用全功能；
- 两者的成本都不在 License，而在“装完不能用”：Sa-Token 需要你已经有登录体系，Spring Authorization Server 需要你自己写登录页、用户管理、同意页、MFA 和审计。

### 2.5 三条硬标准

不管选哪个，先确认这三件事：

1. **可商用**：许可证允许你所在的组织使用、修改、私有化；
2. **可退出**：对外只暴露标准 OIDC，业务代码不绑 SDK，随时能换（Sa-Token 是例外，这是它最大的代价）；
3. **可维护**：有人能升级、能排障、能扛住登录故障，而不是“装上就算完”。

---

## 3. 两个产品型 IdP 的功能对比

| 维度 | Keycloak | MaxKey |
|---|---|---|
| 登录方式 | 用户名密码、OTP、WebAuthn、社交登录、身份代理 | 用户名密码、OTP、短信、社交登录、扫码等 |
| 用户来源 | 内置库、LDAP/AD、Kerberos | 内置库、LDAP/AD、SCIM、组织架构同步 |
| 角色模型 | Realm 角色、Client 角色、组合角色、组 | 角色、用户组、组织、应用授权 |
| 角色是否进 Token | 是（`realm_access.roles`、`resource_access`） | **否**（ID Token 与 UserInfo 都不含角色） |
| 单点注销 | RP-Initiated Logout、Backchannel Logout | RP 发起注销、`/sign/force/logout`；backchannel 需按版本确认 |
| 多租户 | Realm 隔离；Organizations | 机构（instId）隔离 |
| 中文后台 | 有语言包，但翻译不全 | 原生中文 |
| 授权服务 | 内置 Authorization Services（细粒度策略） | 以 RBAC + 应用授权为主 |
| 扩展方式 | SPI、自定义 Provider、主题 | 适配器、扩展 API、源码定制 |
| 资料可查性 | 高，英文社区大 | 中低，问题更多靠官方文档和源码 |

两个差异值得单独说明。

### 3.1 角色：Keycloak 能直接映射，MaxKey 不能

Keycloak 把角色写进 Token，Spring 侧一个 `GrantedAuthoritiesMapper` 或 `JwtAuthenticationConverter` 就能变成 `ROLE_xxx`。

MaxKey 的 OIDC 实现里，ID Token 只有 `sub`、`iss`、`aud`、`iat`、`exp`、`jti` 这些标准声明；UserInfo 按 scope 返回用户名、姓名、部门、邮箱等属性，**没有角色字段**。所以：

- 粗粒度可以按 `department` 之类的属性做映射；
- 正经做法是登录后按 `sub`（默认取用户名）到业务库查角色；
- 指望“在 MaxKey 配好角色，Spring 里 `hasRole('admin')` 就生效”，在 OIDC 这条路上走不通。

### 3.2 注销：都能做，但实现方式不同

- Keycloak 有标准 `end_session_endpoint`，Spring 的 `OidcClientInitiatedLogoutSuccessHandler` 可以直接用；
- MaxKey 的注销入口是 `/sign/force/logout?redirect_uri=...`，通常要自己写一个 `LogoutSuccessHandler` 跳过去；
- 两者默认都只保证“当前应用 + IdP 会话”退出，其他系统的本地 Session 不会自动消失。要即时全局退出，需要 backchannel 或更短的 Session 策略。

---

## 4. 框架型选项：Sa-Token 与 Spring Authorization Server

上面两个是“产品型 IdP”：装好就有管理台、用户库、登录页、MFA。下面两个是“框架型”：同样免费，但只给你登录态或协议能力，界面和用户体系要自己补。

### 4.1 Sa-Token：最轻的登录态共享

- 版本 v1.46.0（2026-08-19），Apache 2.0，Maven 坐标 `cn.dev33:sa-token-sso:1.46.0`；
- 定位是 Java 权限认证框架，SSO 只是其中一个模块；
- 优点：接入极简，支持同域、跨域、共享 Redis 三种 SSO 模式，中文文档完整；
- 代价：**走自己的 ticket 协议，不是标准 OIDC/SAML**；只服务 Java 侧，第三方、非 Java 系统、移动端接入都很弱；以后想换 IdP，基本等于重做；
- 适合：2～5 个内部 Spring Boot 系统，用户体系完全自己掌握，不对外提供认证。

一句话：**它解决“共享登录态”，不解决“对外提供标准身份”。**

### 4.2 Spring Authorization Server：把认证做进产品

- Apache 2.0，没有付费功能墙；
- 独立仓库已归档到 `spring-attic`，最后独立版本 1.5.8（2026-06-09），基于 Spring Framework 6.2 / Spring Security 6.5，对应 Spring Boot 3.5；
- 后续开发并入 Spring Security 7 的 `oauth2-authorization-server` 模块，Maven 坐标不变，仍是 `org.springframework.security:spring-security-oauth2-authorization-server`；7.1.2 已发布，7.2.0-RC1 于 2026-10 发布。**Boot 3.x 只能用 1.5.x，Boot 4.x 才用 7.x**；
- 它提供的是协议实现：授权码、PKCE、客户端注册、Token 签发、JWK 轮换、OIDC Discovery；
- 它**不提供**用户表、登录页、同意页、MFA、审计、管理后台，这些都要自己写；
- 适合：已有用户中心，要把认证能力产品化，或需要深度定制 Token 与授权模型。

一句话：**免费的是库，不是一套认证服务。**

### 4.3 四个方案怎么归类

| 维度 | Keycloak | MaxKey | Sa-Token | Spring Authorization Server |
|---|---|---|---|---|
| 类型 | 产品型 IdP | 产品型 IdP | 框架（SSO 模块） | 框架（授权服务器） |
| 装完能用 | 能 | 能 | 要接自己的登录 | 不能，先写一套 |
| 标准 OIDC | 是 | 是，有差异 | 否 | 是 |
| 内建用户与管理台 | 有 | 有 | 无 | 无 |
| 免费边界 | Apache 2.0 全功能 | Apache 2.0 + 商业服务 | Apache 2.0 | Apache 2.0 |
| 主要成本 | 运维 | 运维 + 生态小 | 协议锁定 | 开发量 |
| 适合 | 多系统、第三方 | 国内多协议 | 内部几个 Java 系统 | 认证产品化 |

---

## 5. Spring Boot 接入成本：差别在细节

很多人以为“都支持 OIDC，接法一样”。对两个产品型 IdP 来说方向没错，但落地时差别不小。

### 5.1 Keycloak：配置即接入

```yaml
spring:
  security:
    oauth2:
      client:
        registration:
          keycloak:
            provider: keycloak
            client-id: blog-web
            client-secret: ${KEYCLOAK_CLIENT_SECRET}
            authorization-grant-type: authorization_code
            scope: openid,profile,email
        provider:
          keycloak:
            issuer-uri: http://localhost:8080/realms/blog
```

- 发现文档完整，授权端点、Token 端点、JWK、UserInfo、注销端点都能自动拿到；
- 角色在 `realm_access.roles`；
- 注销用现成的 handler。

### 5.2 MaxKey：能接，但要手配端点

MaxKey 4.2.0 的发现文档位于 `/sign/authz/oauth/v20/.well-known/openid-configuration`，而 Spring Security 会把 `issuer-uri` 拼成 `<issuer>/.well-known/openid-configuration`，并且**要求发现文档里的 `issuer` 与配置值完全一致**。MaxKey 在不带 `client_id` 参数时返回的 `issuer` 是带 `/maxkey` 的上下文形态，两边对不上，所以直接用 `issuer-uri` 会报 issuer 不匹配。

实际可行的做法是显式配置端点：

```yaml
spring:
  security:
    oauth2:
      client:
        provider:
          maxkey:
            authorization-uri: http://localhost:9527/sign/authz/oauth/v20/authorize
            token-uri: http://localhost:9527/sign/authz/oauth/v20/token
            user-info-uri: http://localhost:9527/sign/api/connect/v10/userinfo
            jwk-set-uri: http://localhost:9527/sign/authz/oauth/v20/jwks
```

此外还有三个默认值必须先改，否则登录大概率失败：

1. **scope 默认只有 `read`**：要手动加上 `openid`、`profile`、`email`，否则拿不到 ID Token；
2. **签名算法默认是空**：不选算法时 ID Token 不带签名，Spring 校验会失败，要选 `RS256`；
3. **UserInfo 返回格式默认是 JWT**：Spring 按 JSON 解析用户信息，建议把返回格式改成 `NORMAL`（JSON）。

这些都是配置层面的成本，不是写代码的成本，但第一次接的人很容易卡在这儿。

### 5.3 代码复用度

登录、Session、权限控制、注销这些 Spring 侧结构可以复用，但**不能只改 `issuer-uri` 就切换**。从 Keycloak 换到 MaxKey，至少要改：

- provider 配置（发现 → 显式端点）；
- 角色来源（Token claim → 业务库查询）；
- 注销处理（标准 handler → 自定义跳转）；
- 用户信息取值（claims 名称不同）。

---

## 6. 按场景怎么选

如果目标是“把认证能力做进产品”，下面这棵树不适用，直接看 Spring Authorization Server。

```text
只有 2～5 个内部 Java 系统，且不接第三方？
├─ 是 → Sa-Token（最轻，但锁在自有协议上）
└─ 否 → 有中文管理后台的硬性要求吗？
         ├─ 有 → 需要 CAS/SAML/SCIM 等存量协议吗？
         │        ├─ 需要 → MaxKey（先 POC）
         │        └─ 不需要 → 能接受多维护 MySQL + Redis + Tomcat 吗？
         │                 ├─ 能 → MaxKey
         │                 └─ 不能 → Keycloak
         └─ 没有 → 团队更看重资料多、踩坑少吗？
                  ├─ 是 → Keycloak
                  └─ 否 → 两个都可以，按运维习惯选
```

更直接的判断：

1. **多系统、多端、要接第三方、长期维护**：Keycloak；
2. **国内政企、中文后台、CAS/SAML/OIDC 混合**：MaxKey；
3. **团队没有专职中间件运维**：Keycloak，组件更少；
4. **已有 LDAP/AD，且需要中文账号生命周期界面**：MaxKey；
5. **只是 2～5 个内部 Spring Boot 系统共享登录态**：Sa-Token，比上两个都轻；
6. **已有用户中心，要把认证能力产品化**：Spring Authorization Server（Boot 3.5 用 1.5.x，Boot 4 用 7.x）；
7. **要强定制但不想自己写协议**：在 Keycloak/MaxKey 上做扩展，而不是自研。

---

## 7. 选 MaxKey 的 POC 清单

如果你倾向 MaxKey，不要只看官网截图，至少验证这 8 件事。

1. **OIDC 端点**：授权、Token、UserInfo、JWKS 是否都能访问；Spring 用显式端点能否完成登录。
2. **scope 与 Token**：加上 `openid,profile,email` 后，ID Token 的 `alg` 是不是 RS256，`aud` 是否等于 clientId。
3. **UserInfo 格式**：返回 JSON 还是 JWT；字段名是否符合预期（例如 `preferred_username` 取的是显示名，不是登录名）。
4. **角色来源**：确认 Token 里没有角色后，业务侧的授权方案是什么。
5. **注销**：`/sign/force/logout` 是否按预期清理 IdP 会话并跳回业务系统。
6. **LDAP/AD/SCIM**：同步方向、字段映射、禁用用户是否及时生效。
7. **审计与备份**：登录日志、管理操作日志、数据库与签名密钥的备份恢复。
8. **付费边界**：国密、等保材料、行业适配、厂商支持，逐项书面确认。

再加一条：**退出预案**。对外只暴露标准 OIDC，不要把业务代码绑死在某个产品的 SDK 上。

---

## 8. 结论

这不是说 MaxKey 不好。它在中文后台、多协议兼容、国产化场景上确实有优势，Apache 2.0 也足够干净。问题在于：**它的生态和“Spring Boot 开箱即用”的程度不如 Keycloak**，你需要为这些差异付出配置和排障成本。

Sa-Token 和 Spring Authorization Server 同样免费，但没有放进本系列的实战：前者走自有协议，后者要自己补齐用户体系。如果你的场景已经明确落在“内部几个 Java 系统”或“认证产品化”上，直接按第 4 节选就行，不必先跟着跑 Keycloak。

本系列的选择是：

- **Keycloak 作为基准**，先把标准 OIDC 接法讲透；
- **MaxKey 单独写一篇**，把上面提到的端点、签名、UserInfo、角色问题逐个落到配置和代码上。

接下来的两篇：

- 《Spring Boot 3 接入 Keycloak 实战》：Docker 启动、客户端配置、`SecurityConfig`、角色映射、单点注销；
- 《Spring Boot 3 接入 MaxKey 实战》：应用注册、显式端点、签名与 UserInfo 格式、无角色 claim 时的授权方案、注销跳转。

---

## 参考资料

- [Keycloak 官方网站](https://www.keycloak.org/)
- [Keycloak License](https://github.com/keycloak/keycloak/blob/main/LICENSE.txt)
- [Keycloak Releases](https://github.com/keycloak/keycloak/releases)
- [MaxKey 官方网站](https://www.maxkey.org/)
- [MaxKey 许可证说明](https://www.maxkey.org/zh/about/licenses.html)
- [MaxKey 社区版与企业版](https://www.maxkey.org/zh/about/cevsenterprise.html)
- [MaxKey Releases](https://github.com/dromara/MaxKey/releases)
- [MaxKey OIDC 文档](https://www.maxkey.org/zh/am/sso/oidc.html)
- [Sa-Token GitHub](https://github.com/dromara/Sa-Token)
- [Sa-Token 官方文档](https://sa-token.cc/)
- [Spring Authorization Server（归档仓库）](https://github.com/spring-attic/spring-authorization-server)
- [Spring Security Releases](https://github.com/spring-projects/spring-security/releases)
- [Spring Security OAuth2 Reference](https://docs.spring.io/spring-security/reference/servlet/oauth2/index.html)

Java 开源单点登录怎么选？Keycloak、MaxKey 与两个框架型方案对比

dy解析联动快捷路径

从 JDK 8 到 JDK 21（三）Spring 迁移篇：Boot 2.x → 3.x → 虚拟线程

同一段代码，从 JDK 8 换到 JDK 21，语法一个字没改，行为却可能变：启动时多了一个 `InaccessibleObjectException`，日志里的中文突然乱码，老 GC 参数不生效，某个脚本引擎找不到实现。

语言篇讲的是“怎么写”，这篇讲“跑起来之后会发生什么”。升级真正让人加班的部分，大多在这里。

> **TL;DR**
> - JPMS 对 Spring 应用的真实影响是**强封装**，不是逼你写 `module-info.java`。
> - G1 已是默认；ZGC 适合大堆低延迟，但要压测后再换；容器里优先用 `MaxRAMPercentage`。
> - JDK 18 起 `file.encoding` 默认 UTF-8，这是中文项目最容易被忽略的隐性变更。
> - Java EE/CORBA、CMS、Nashorn 已被移除；CDS 和 JFR 是升级顺带的收益。

---



## 一、运行时变化时间线

| 版本 | 关键变化 |
|---|---|
| 9 | JPMS 模块系统、G1 成为默认 GC、Compact Strings、jlink、jshell |
| 10 | 容器感知、G1 并行 Full GC、应用 CDS |
| 11 | 移除 Java EE/CORBA、ZGC（实验）、TLS 1.3、JFR 开源、Epsilon GC |
| 12 | Shenandoah（实验）、G1 归还空闲内存 |
| 13 | 动态 CDS、ZGC 归还内存、Socket API 重写 |
| 14 | 友好 NPE、移除 CMS、jpackage（孵化）、JFR Event Streaming |
| 15 | ZGC/Shenandoah 转正、移除 Nashorn、偏向锁禁用 |
| 16 | 强封装默认开启、弹性元空间、jpackage 正式 |
| 17 | 强封装强制、`--illegal-access` 失效、浮点始终严格 |
| 18 | **UTF-8 成为默认字符集**、`finalize` 弃用 |
| 19 | 虚拟线程（预览） |
| 21 | 虚拟线程正式、分代 ZGC、KEM API |

---

## 二、JPMS 与强封装

### 1. 不需要为了 Spring 写 `module-info.java`

JPMS（Java Platform Module System）把 JDK 拆成了模块，也允许应用自己声明模块。但绝大多数 Spring Boot 应用仍然跑在 **classpath（未命名模块）** 上，不需要写 `module-info.java`，也不需要把依赖迁到 module path。

真正会咬人的是另一件事：**强封装**。

- JDK 16 起，非法反射访问 JDK 内部 API 默认被拒绝。
- JDK 17 起，`--illegal-access` 被忽略，不能再靠它统一放行。

老库如果反射 `java.lang`、`java.util`、`java.nio` 的内部结构，就会抛：

```text
java.lang.reflect.InaccessibleObjectException:
Unable to make field private final byte[] java.lang.String.value accessible:
module java.base does not "opens java.lang" to unnamed module @6f1fba17
```

### 2. 先定位，再决定要不要 `--add-opens`

```bash
# 找出使用了 JDK 内部 API 的依赖
jdeps --jdk-internals target/app.jar

# 找出使用了已废弃 API 的类
jdeprscan --release 21 target/classes
```

`jdeps --jdk-internals` 会列出 `sun.misc.Unsafe`、`jdk.internal.*` 之类的使用点；`jdeprscan` 会告诉你哪些 API 在目标版本已被废弃或移除。

处理优先级：

1. **升级依赖**：CGLIB、Lombok、Byte Buddy、Netty、Mockito、Hibernate 的新版本通常已经适配。
2. **换实现**：去掉对 `sun.misc.Unsafe`、内部序列化结构的依赖。
3. **`--add-opens` 兜底**：只对确认无法短期升级的库使用，并记录原因。

```bash
java --add-opens java.base/java.lang=ALL-UNNAMED --add-opens java.base/java.util=ALL-UNNAMED -jar app.jar
```

`ALL-UNNAMED` 表示“classpath 上的所有代码”。它能解决问题，但也会扩大反射面，不要把它当成默认配置复制到所有服务。

`--add-opens` 是运行时deep reflection 放行；如果是编译期依赖 JDK 内部 API，还需要 `--add-exports`。两者都不是长久方案。

---

## 三、GC 与容器

### 1. 先记住这几个事实

- JDK 9 起 **G1 成为默认 GC**，Java 8 时代常用的 CMS 在 JDK 14 被移除。
- JDK 10 起支持容器感知（8u191 也回移了），JVM 会读取 cgroup 的 CPU/内存限制。
- JDK 11 ZGC 实验，JDK 15 转正，JDK 21 提供**分代 ZGC**。
- JDK 12 Shenandoah 实验，JDK 15 转正；是否可用取决于 JDK 发行版。
- JDK 23 起分代 ZGC 成为默认的非分代替代方案，非分代 ZGC 逐步退场。

### 2. 怎么选

| 场景 | 建议 |
|---|---|
| 通用 Web 服务、堆不大 | G1（默认） |
| 大堆、对暂停时间敏感 | ZGC（先压测） |
| 小内存容器、单核/少核 | SerialGC 或 G1，按实测 |
| 追求吞吐、能接受较长停顿 | ParallelGC |
| 极低暂停、发行版支持 | Shenandoah |

没有“最好的 GC”，只有“对这个堆大小、分配速率和延迟目标最合适的 GC”。切换前至少记录：吞吐、p99、Full GC 次数、单次最长暂停、容器内存曲线。

### 3. 容器里的内存参数

不要再用固定 `-Xmx`，除非你非常确定容器的内存规格：

```bash
-XX:+UseG1GC
-XX:MaxRAMPercentage=70
-XX:InitialRAMPercentage=30
-XX:+HeapDumpOnOutOfMemoryError
-XX:HeapDumpPath=/var/log/app
-Xlog:gc*:file=/var/log/app/gc.log:time,uptime,level,tags:filecount=5,filesize=20m
```

- `MaxRAMPercentage=70` 给堆外内存、线程栈、元空间、直接内存留出余量。
- 如果 CPU limit 识别不准，可以用 `-XX:ActiveProcessorCount=4` 显式指定，但优先修容器配置。
- 堆 dump 路径要挂持久卷，否则 Pod 重启后文件就没了。

低延迟服务可以试：

```bash
-XX:+UseZGC -XX:+ZGenerational -XX:MaxRAMPercentage=70
```

ZGC 不是“无脑更快”。小堆、短生命周期对象多的场景，G1 往往更稳；ZGC 的收益主要体现在大堆和低暂停目标上。**先压测，再换 GC。**

### 4. 排查命令

```bash
# 堆与 GC 概况
jcmd <pid> GC.heap_info
jstat -gcutil <pid> 1000

# 原生内存跟踪（有额外开销，排障时开）
-XX:NativeMemoryTracking=summary
jcmd <pid> VM.native_memory summary

# 线程栈
jcmd <pid> Thread.print
```

GC 日志里重点看：

- Young GC 频率和耗时
- Full GC 是否出现
- 每次 GC 后老年代占用是否持续上升（内存泄漏信号）
- 堆外内存是否增长（NMT）

---

## 四、友好 NPE（JDK 14 引入，15 默认开启）

Java 8：

```text
Exception in thread "main" java.lang.NullPointerException
    at com.example.OrderService.create(OrderService.java:42)
```

Java 15+：

```text
Exception in thread "main" java.lang.NullPointerException:
Cannot invoke "String.length()" because "name" is null
    at com.example.OrderService.create(OrderService.java:42)
```

不需要改代码，升级就有。它依赖编译时保留局部变量表；Maven 的 `debug` 默认是 true，一般没问题。如果看到 `<local1>` 这样的名字，检查一下是否关掉了调试信息。

注意：这只是排障辅助，不要把异常消息格式当成稳定 API 去解析。

---

## 五、被删掉的东西

| 版本 | 移除/禁用 | 替代 |
|---|---|---|
| 11 | Java EE 模块、CORBA | 显式引入 Jakarta 依赖 |
| 14 | CMS GC、Pack200 | G1/ZGC；jlink/jpackage |
| 15 | Nashorn | GraalJS 或其他 JS 引擎 |
| 15 | 偏向锁禁用 | 重新评估高竞争 `synchronized` |
| 17 | SecurityManager 弃用 | 容器/OS 权限控制 |
| 18 | `finalize` 弃用 | try-with-resources / Cleaner |

几个最常见的迁移点：

**1. JAXB / JAX-WS**

JDK 11 移除了 Java EE 模块，`javax.xml.bind.*`、`javax.xml.ws.*` 不再随 JDK 提供。需要显式加 `jakarta.xml.bind-api` 和对应的运行时实现（如 `jaxb-runtime`），或者改用 Jackson 处理 XML。

**2. `javax.annotation`**

`@PostConstruct`、`@Resource` 这些注解在 JDK 11+ 不再自带。Spring Boot 3 里统一换成 `jakarta.annotation.*`，由 starter 带入依赖。

**3. `sun.misc.BASE64Encoder`**

JDK 9 就移除了，换成 `java.util.Base64`：

```java
var encoded = Base64.getEncoder().encodeToString(bytes);
```

**4. Nashorn**

JDK 15 移除。以前用 `ScriptEngineManager().getEngineByName("nashorn")` 执行 JS 的代码，需要换 GraalJS，或者把这段逻辑改成 Java/服务化。

**5. `finalize`**

不是立刻删除，但不要再用它释放资源。用 try-with-resources，或者 `Cleaner`（JDK 9+）作为兜底。

---

## 六、UTF-8 成为默认字符集（JDK 18）

### 1. 变化是什么

JEP 400 之后，`file.encoding` 默认是 UTF-8。对中文 Windows 项目，这意味着：

- 以前默认可能是 GBK，`new FileReader(file)`、`new FileWriter(file)`、`String.getBytes()` 这类不显式指定编码的代码，行为变了。
- 控制台编码不一定跟着变。中文 Windows 的 `native.encoding` 仍然可能是 GBK，日志可能依旧乱码。

### 2. 怎么修

原则只有一条：**所有跨字节的边界都显式指定字符集**。

```java
Files.readString(path, StandardCharsets.UTF_8);
Files.writeString(path, content, StandardCharsets.UTF_8);
string.getBytes(StandardCharsets.UTF_8);
new String(bytes, StandardCharsets.UTF_8);
```

不要依赖：

```java
new FileReader(file);   // 使用默认编码
new FileWriter(file);   // 使用默认编码
string.getBytes();      // 使用默认编码
```

### 3. JVM 参数

```bash
# 统一文件编码
-Dfile.encoding=UTF-8

# JDK 19+ 可以单独指定标准输出/错误输出编码
-Dstdout.encoding=UTF-8
-Dstderr.encoding=UTF-8
```

如果必须兼容旧行为，可以临时：

```bash
-Dfile.encoding=COMPAT
```

但这是权宜之计，不要把它写进长期启动脚本。

### 4. Spring 侧配置

```yaml
server:
  servlet:
    encoding:
      charset: UTF-8
      force: true
spring:
  messages:
    encoding: UTF-8
logging:
  charset:
    console: UTF-8
    file: UTF-8
```

数据库和 JDBC 也要一起确认：

- MySQL 连接串加 `characterEncoding=utf8`（或 `utf8mb4` 对应配置）。
- 表/列的字符集用 `utf8mb4`，避免 emoji 和四字节字符丢失。
- 文件上传、模板渲染、CSV 导出都要显式指定编码。

### 5. 一个容易误解的点

**Compact Strings 对中文帮助有限。** 它只对 Latin-1 字符压缩到 1 字节，中文仍然是 2 字节/字符。不要指望升级后中文文本内存直接减半。

---

## 七、启动、镜像与观测

### 1. 应用 CDS

类数据共享可以把常用类提前归档，缩短启动时间：

```bash
# 训练：跑一遍典型启动流程
java -XX:ArchiveClassesAtExit=app.jsa -jar app.jar

# 生产：使用归档
java -XX:SharedArchiveFile=app.jsa -jar app.jar
```

训练用的 JDK 版本、启动参数、依赖要和生产一致，否则归档可能失效。Spring Boot 3.3+ 对 CDS 有更好的支持，可以结合分层提取使用。

### 2. JFR

JFR 从 JDK 11 起开源，生产环境可以直接开：

```bash
-XX:StartFlightRecording=filename=app.jfr,settings=profile,dumponexit=true
```

运行时也可以手动采集：

```bash
jcmd <pid> JFR.start name=profile settings=profile duration=60s filename=app.jfr
jfr summary app.jfr
jfr print --events jdk.GCPhasePause app.jfr
```

JFR 对定位 GC、线程阻塞、锁竞争、虚拟线程 pinning 都很有用，开销通常比想象中小。

### 3. jlink / jpackage

`jlink` 用来裁剪定制运行时，`jpackage` 用来打原生安装包。它们适合工具类应用和桌面应用；Spring Boot fat jar 不是天然契合，真要做裁剪，Boot 3.3+ 的 `tools` jarmode 可以先分层提取。

大多数服务不需要走到这一步，标准 JDK 镜像 + CDS 已经够用。

### 4. AOT 与 Native Image

Spring Boot 3 支持 GraalVM Native Image，可以把应用编译成原生可执行文件，换来更快的启动和更低的内存占用。代价是：

- 构建时间长、产物大
- 反射、动态代理、资源加载需要 `RuntimeHints` 或注解显式注册
- 峰值吞吐不一定比 JVM 好
- 与虚拟线程、动态字节码增强的组合需要逐项验证

如果团队没有明确的启动时间/内存硬指标，JVM 模式 + 虚拟线程通常是更划算的选择。

### 5. 容器镜像

- 用 Temurin、Corretto、Zulu 等有长期维护的发行版。
- 基础镜像和构建 JDK 版本保持一致。
- 容器里用 `MaxRAMPercentage`，不要写死 `-Xmx`。
- 健康检查、优雅停机、堆 dump 路径一起配好。
- 不要把 `--enable-preview` 带进生产镜像。

---

## 八、运行时升级检查清单

- [ ] 先在 JDK 17 上跑通全量测试，再上 21。
- [ ] `jdeps --jdk-internals` 和 `jdeprscan` 检查内部 API、废弃 API。
- [ ] 确认没有依赖自定义 agent、字节码增强、老版本 CGLIB/Lombok/Byte Buddy。
- [ ] 搜索 `new FileReader`、`new FileWriter`、`getBytes()` 无参调用。
- [ ] 用中文内容做一次文件读写、CSV 导出、日志输出验证。
- [ ] 记录升级前的 GC 日志、堆使用、p99 作为基线。
- [ ] 配好 `HeapDumpOnOutOfMemoryError` 和持久化路径。
- [ ] 确认容器内存/CPU limit 与 `MaxRAMPercentage` 匹配。
- [ ] 开启 JFR，至少保留一份启动和压测期间的记录。
- [ ] 准备回滚镜像和回滚开关。

---

## 九、小结

运行时升级的核心不是“调几个参数”，而是**确认行为变化**：反射能不能过、字符集有没有变、GC 在容器里是否读对了限制、被移除的 API 有没有替代。

下一篇进入 Spring：为什么真正的门槛是 Boot 3 的 `javax` → `jakarta`，record/sealed 怎么落到项目里，虚拟线程开了之后为什么 QPS 可能不涨。

本系列共三篇：

1. 语言篇：语法现代化与标准库
2. 运行时篇：JPMS、GC、字符集与启动
3. Spring 迁移篇：Boot 2.x → 3.x → 虚拟线程