@gsc-basic/service-auth

Services Auth for GSC Basic Team

说明

各服务打通认证的关键工具

快速说明

• 目的：统一获取并缓存服务间访问 Token（包含自动过期监测与刷新）。
• 适用场景：前端或服务端需要代表应用调用内部服务时获取短期 service token。

Options 字段说明

| 字段 | 类型 | 默认 | 说明 | |---|---:|---|---| | token | string | '' | 应用静态凭证，用于非自定义请求方法时向授权服务换取 service token | | tokenHeader | string | '' | 当使用 token 时，额外的 header 名称（例如 X-App-Token） | | requestBaseUrl | string | '' | API 根地址，会与路径 /gscbasic/auth/token 拼接； | | requestParams | Record<string, any> | null | null | 初始请求体参数 | | tokenRequestMethod | (opts)=>Promise | null | null | 自定义拉取 token 的方法，优先使用此方法，签名为 (opts: { url, requestParams }) | | onTokenChange | (res)=>void | ()=>{} | token 变更回调（持久化/刷新时触发） |

导出方法说明

| 方法 | 参数 | 返回 | 说明 | |---|---|---|---| | setBasicAuth | {forceFetch?: boolean} | Promise<string | null> | 主动获取并缓存 service token；forceFetch 强制绕过缓存 | | getBasicToken | {forceFetch?: boolean} | Promise<string | null> | 读取缓存 token；若过期或 forceFetch 则触发刷新 | | removeBasicToken | — | void | 清除本地缓存并停止过期监测器 | | setRequestParams | params: any | void | 设置调用授权服务时的请求体参数 | | setRequestBaseUrl | requestBaseUrl: string | void | 设置 requestBaseUrl（宿主代理或 API 根地址），后续请求会使用该值 |

行为细节 & 注意事项

• token 缓存位置：window.localStorage + 挂载在 window 的快捷键（便于跨 context 访问）。
• 过期检测：使用内部 createTokenExpiryMonitor 自动在 token 过期时清理并触发重新获取。
• 错误处理：HTTP 请求失败会以 rejected Promise 形式返回错误，调用方请使用 try/catch。
• 自定义请求：推荐使用 tokenRequestMethod 注入自定义请求逻辑（例如带统一签名、proxy 等）。

示例：自定义 tokenRequestMethod

const auth = useBasicAuth({
	tokenRequestMethod: async ({ url, requestParams }) => {
		// 自行实现 fetch/axios 请求并返回 TokenResponse
		const res = await fetch(url, { method: 'POST', body: JSON.stringify(requestParams) });
		if (!res.ok) throw new Error('auth failed');
		return res.json();
	}
});

await auth.setBasicAuth();

Author & License

This package is maintained by Lenovo SSG BASD. It is distributed under the LicenseRef-Proprietary license; see LICENSE for details.