外观
跨服务 RPC 集成
2026-04-01
业务服务(如 nebula-system、业务微服务)通过
AuthRpcService调用 nebula-auth 的认证能力,无需直接操作认证数据库。
框架通过「三件套」模式(Feign Client + LocalStub + Constants)支持聚合部署和独立部署两种场景。
目录
一、AuthRpcService 接口总览
AuthRpcService 定义在 nebula-auth-api 模块中,提供以下能力:
| 方法 | HTTP | 路径 | 说明 |
|---|---|---|---|
login | POST | /rpc/nebula/auth/auth/login | 以编程方式触发登录(获取 Token) |
me | GET | /rpc/nebula/auth/auth/me | 通过 Token 获取当前用户信息 |
createAccount | POST | /rpc/nebula/auth/auth/account | 创建认证账号 |
updateCredential | PUT | /rpc/nebula/auth/auth/account/credential | 修改账号密码 |
syncAccountStatus | PATCH | /rpc/nebula/auth/auth/account/{accountId}/status | 同步账号状态(启用/禁用) |
二、接入方式
2.1 引入依赖
在调用方服务的 build.gradle 中引入 nebula-auth-api:
dependencies {
implementation "com.huida.nebula.auth:nebula-auth-api:${nebulaAuthVersion}"
}2.2 启用 Feign
在服务的启动类或配置类上启用 Feign:
@EnableFeignClients(basePackages = "com.huida.nebula.auth.api")
@SpringBootApplication
public class MyServiceApplication { ... }2.3 注入并使用
@Service
@RequiredArgsConstructor
public class MyUserService {
private final AuthRpcService authRpcService;
public void createUser(UserSaveParam param) {
// ... 创建业务用户 ...
// 同步创建认证账号
AuthAccountCreateRequest request = new AuthAccountCreateRequest();
request.setLoginName(param.getUsername());
request.setPassword(param.getInitPassword());
authRpcService.createAccount(request).getDataOrThrow();
}
}三、接口详细说明
3.1 login —— 编程式登录
通过代码触发登录流程,获取 Token(适用于内部系统自动化登录场景)。
AuthLoginRequest request = new AuthLoginRequest();
request.setUsername("admin");
request.setPassword("password");
R<AuthLoginTokenDTO> result = authRpcService.login(request);
AuthLoginTokenDTO tokenDTO = result.getDataOrThrow();
String accessToken = tokenDTO.getAccessToken();
String refreshToken = tokenDTO.getRefreshToken();AuthLoginTokenDTO 字段:
| 字段 | 说明 |
|---|---|
accessToken | 访问令牌 |
refreshToken | 刷新令牌 |
accessTokenExpireAt | AccessToken 过期时间 |
refreshTokenExpireAt | RefreshToken 过期时间 |
expiresIn | AccessToken 有效秒数 |
tokenType | Bearer |
3.2 me —— 通过 Token 获取用户信息
在网关或业务服务中,通过前端传来的 Token 查询用户信息:
String authorization = "Bearer " + accessToken;
R<AuthUserDTO> result = authRpcService.me(authorization);
AuthUserDTO user = result.getDataOrThrow();
Long userId = user.getUserId();
String username = user.getUsername();
Long tenantId = user.getTenantId();注意: 大多数场景下不需要调用此接口,框架在请求进入时已自动解析 Token 并注入 SecurityContext,直接通过
SecurityContextHolder.getContext().getAuthentication()或框架封装的工具类获取当前用户即可。
3.3 createAccount —— 创建认证账号
AuthAccountCreateRequest request = new AuthAccountCreateRequest();
request.setLoginName("user001"); // 登录名(全局唯一)
request.setPassword("Init@123456"); // 初始密码(明文,auth 内部哈希存储)
request.setAccountType("NORMAL"); // 账号类型
R<Long> result = authRpcService.createAccount(request);
Long authAccountId = result.getDataOrThrow(); // 返回认证账号 ID3.4 updateCredential —— 修改密码
AuthCredentialUpdateRequest request = new AuthCredentialUpdateRequest();
request.setLoginName("user001");
request.setNewPassword("New@123456");
// request.setOldPassword("Init@123456"); // 可选:旧密码验证
authRpcService.updateCredential(request);3.5 syncAccountStatus —— 同步账号状态
当业务系统启用/禁用用户时,同步更新认证账号状态:
// 禁用(status = 1)
authRpcService.syncAccountStatus(authAccountId, 1);
// 启用(status = 0)
authRpcService.syncAccountStatus(authAccountId, 0);四、部署模式说明
AuthRpcService 通过「三件套」支持两种部署模式,调用方无需感知当前的部署模式:
业务服务代码
│
▼
AuthRpcService(接口)
│
├─ 聚合部署(同 JVM):AuthRpcServiceLocalStub(@Primary)
│ └── 直接调用本地 LoginService / IAuthAccountService
│
└─ 独立部署(不同 JVM):Feign HTTP 代理
└── 发 HTTP 请求到 → nebula-auth 服务| 部署模式 | 生效 Bean | 调用开销 |
|---|---|---|
| 聚合部署(monolith) | AuthRpcServiceLocalStub(@Primary) | 本地方法调用,无网络开销 |
| 独立部署(microservice) | Feign HTTP 代理 | HTTP 网络请求 |
聚合部署时,
nebula-auth-core和业务服务在同一个 Spring 应用中,LocalStub 直接短路调用本地 Service,不经过 HTTP。
五、RPC 常量参考
来自 nebula-auth-api 的 AuthConstants:
public final class AuthConstants {
// 服务名(Nacos 注册名 / Feign Client name)
public static final String SERVICE_NAME = "nebula-auth";
// RPC 路径前缀
public static final String URI_PREFIX = CommonConstants.RPC_URI_PREFIX + "/nebula/auth";
// 最终值:/rpc/nebula/auth
private AuthConstants() {}
}各 RPC 接口完整路径(供直接 HTTP 调用时参考):
| 接口 | 完整路径 |
|---|---|
| 登录 | POST /rpc/nebula/auth/auth/login |
| 获取用户信息 | GET /rpc/nebula/auth/auth/me |
| 创建账号 | POST /rpc/nebula/auth/auth/account |
| 修改密码 | PUT /rpc/nebula/auth/auth/account/credential |
| 同步状态 | PATCH /rpc/nebula/auth/auth/account/{accountId}/status |
| 按 clientId 查询 OAuth2 客户端 | GET /rpc/nebula/auth/oauth2-client/by-client-id |
