业务服务（如 nebula-system、业务微服务）通过 AuthRpcService 调用 nebula-auth 的认证能力，无需直接操作认证数据库。
框架通过「三件套」模式（Feign Client + LocalStub + Constants）支持聚合部署和独立部署两种场景。

---

目录

• 一、AuthRpcService 接口总览
• 二、接入方式
• 三、接口详细说明
• 四、部署模式说明
• 五、RPC 常量参考

---

一、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();  // 返回认证账号 ID

3.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