SpringBoot3 + OAuth2.1实战：如何优雅地通过代码管理客户端信息（附完整SQL脚本）

SpringBoot3 + OAuth2.1实战：如何优雅地通过代码管理客户端信息（附完整SQL脚本）

最近在重构一个微服务项目的认证授权模块，从OAuth2.0升级到OAuth2.1，最让我头疼的不是新协议的变化，而是客户端信息的管理。团队里有人习惯直接写SQL脚本插入数据库，有人喜欢在代码里硬编码配置，结果就是每次新增一个第三方应用接入，要么得找DBA执行脚本，要么得重新打包部署。更麻烦的是，OAuth2.1里那些client_settings和token_settings的JSON格式配置，手动拼写简直就是灾难，一个标点符号错了，整个认证流程就崩了。

这篇文章就是来解决这个痛点的。我会分享一套在SpringBoot3项目中，通过代码优雅管理OAuth2.1客户端信息的完整方案。这套方案不仅提供了可复用的RESTful接口，让你能动态增删改查客户端配置，还彻底解决了那两个棘手的JSON字段的序列化问题。无论你是正在搭建新的授权服务器，还是想把老项目里混乱的客户端管理方式规范化，相信接下来的内容都能给你带来直接的帮助。

1. 为什么必须放弃SQL脚本管理客户端？

在OAuth2.1的实践中，很多开发者拿到官方SQL脚本建完表后，第一个念头就是：直接写INSERT语句把客户端信息灌进去。这看起来简单直接，尤其是在项目初期只有一两个客户端的时候。但只要你稍微深入一点，就会发现问题接踵而至。

首先，最直观的就是oauth2_registered_client表中的client_settings和token_settings字段。它们不是普通的VARCHAR，里面存储的是复杂的、带有类型信息的JSON结构。如果你尝试写一个这样的SQL：

INSERT INTO oauth2_registered_client 
(id, client_id, client_name, client_settings, token_settings)
VALUES 
('test-client', 'test-app', '测试应用', '{"requireAuthorizationConsent": true}', '{"accessTokenTimeToLive": 3600}');

执行大概率会失败，或者即使成功了，后续认证时也会报各种反序列化错误。因为Spring Authorization Server在内部使用了一个特定的ObjectMapper配置来读写这些字段，它要求JSON中包含@class这样的类型元数据。手动编写的、符合普通人类阅读习惯的JSON，机器反而认不出来。

其次，是安全与维护性问题。客户端的密钥（client_secret）需要加密存储，你难道要在SQL里手动调用加密函数吗？当授权类型、回调地址、作用域需要变更时，你是准备再写一堆UPDATE语句，还是直接修改生产数据库？缺乏版本控制和审计追踪，是运维的噩梦。

注意：直接操作数据库绕过应用层，意味着所有的业务逻辑校验（如URI格式、作用域合法性）都将失效，也埋下了安全漏洞的隐患。

所以，尽管SQL脚本在初始化表结构时必不可少，但用于日常的客户端信息管理，它绝对是下下策。我们需要一种更可控、更安全、更“工程化”的方式。

2. 核心挑战：驯服client_settings与token_settings的JSON序列化

要让代码能够正确地将客户端设置保存到数据库，关键在于理解Spring Authorization Server内部是如何处理ClientSettings和TokenSettings这两个对象的。这部分的复杂性，是很多开发者掉坑的地方。

当你使用ClientSettings.builder()或TokenSettings.builder()构建好对象后，调用build()方法得到的是一个Settings实例。这个Settings对象内部其实是一个Map<String, Object>。问题在于，这个Map里值的类型五花八门：有Boolean，有String，有Duration，甚至还有像OAuth2TokenFormat这样的自定义类型。Spring默认使用一个配置了特定“默认类型”激活（Default Typing）的ObjectMapper来序列化它，目的是在反序列化时能准确地恢复出原始类型。

这就导致了数据库里存储的JSON长成这样：

{
  "@class": "java.util.Collections$UnmodifiableMap",
  "settings.token.reuse-refresh-tokens": true,
  "settings.token.access-token-time-to-live": ["java.time.Duration", 300],
  "settings.token.access-token-format": {
    "@class": "org.springframework.security.oauth2.server.authorization.settings.OAuth2TokenFormat",
    "value": "self-contained"
  }
}

看到了吗？@class属性指明了Map的具体实现类，Duration类型被序列化为一个数组，第一项是类名，第二项是值。如果你自己用普通的ObjectMapper序列化一个Map，得不到这种结构，反序列化时就会抛出Missing type id property '@class'的错误。

解决方案是，在我们的代码里，序列化时必须复用Spring内部相同的逻辑。我们需要做以下几件事：

1. 获取Settings内部的Map：通过clientSettings.getSettings()方法。
2. 配置一个支持Java 8时间类型的ObjectMapper：引入jackson-datatype-jsr310模块。
3. 激活默认类型（Default Typing）：使用activateDefaultTyping方法，并指定JsonTypeInfo.As.PROPERTY，这样就会自动添加@class属性。
4. 使用这个ObjectMapper序列化Map。

下面是一个工具方法的示例，它创建了一个与Spring内部兼容的ObjectMapper：

import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.json.JsonMapper;
import com