NocoBase 前端 SDK Auth 完全指南登录、登出与 Token 管理【免费下载链接】nocobaseNocoBase is an open-source AI no-code platform for building business systems fast. Instead of generating everything from scratch, AI works on top of production-proven infrastructure and a WYSIWYG no-code interface, so you get both speed and reliability.项目地址: https://gitcode.com/GitHub_Trending/no/nocobase导读Auth是 NocoBase 前端 SDKnocobase/sdk中负责用户认证的核心类它封装了登录signIn、注册signUp、注销signOut等认证接口调用并在本地持久化用户的语言、角色、认证器与 API Token同时通过 axios 请求拦截器为每一次 API 请求自动附加认证与上下文请求头。本文以官方 API 文档 docs/docs/cn/api/sdk/auth.md 为骨架结合 packages/core/sdk/src/Auth.ts 等源码与测试用例完整讲解Auth的实例属性、类方法、底层存储与拦截器机制帮助你掌握在 NocoBase 二次开发中正确使用 SDK 完成用户认证的全套实战方案。概览Auth 类在 SDK 中的定位Auth类主要用于在客户端存取用户信息并请求用户认证相关的接口。在 NocoBase 前端 SDK 中Auth并非独立使用而是作为 APIClient 的一个实例属性存在api.auth。当APIClient被创建时会自动实例化Auth并注册请求拦截器constructor(api: APIClient) { this.api api; this.api.axios.interceptors.request.use(this.middleware.bind(this)); }这段代码位于 Auth.ts意味着从APIClient创建那一刻起后续所有经由此 axios 实例发出的请求都会经过Auth的middleware处理自动携带认证相关的请求头。因此Auth是 NocoBase 前端所有需要登录态请求的守门员。此外Auth是一个可扩展的基类APIClient支持通过authClass配置项替换默认的Auth实现例如接入自定义的第三方登录协议详见下文自定义 Auth 子类一节。实例属性locale、role、token 与 authenticatorAuth暴露四个核心实例属性分别对应当前用户的语言、角色、API Token 与认证器。这四个属性都有对应的 getter 与 setter底层通过getOption/setOption读写APIClient的 storage默认是localStorage属性名类型说明底层存储 Keylocalestring当前用户使用的语言localerolestring当前用户使用的角色roletokenstringAPI 接口 tokenBearer Tokentokenauthenticatorstring当前用户认证时所用的认证器标识auth注意authenticator对应的存储 key 是auth而非authenticator这是源码中 getAuthenticator() 直接返回this.getOption(auth)的结果。存储机制与命名空间Auth的读写最终落在 Storage.ts 中的BaseStorage实现上。APIClient默认使用LocalStoragekey 统一由storagePrefix默认NOCOBASE_加属性名大写拼接而成例如NOCOBASE_TOKENtokenNOCOBASE_AUTH认证器NOCOBASE_LOCALE语言NOCOBASE_ROLE角色在测试用例 api-client.test.ts 中可以验证这一行为执行signIn之后localStorage.getItem(N1_TOKEN)返回登录接口下发的 tokenlocalStorage.getItem(N1_AUTH)返回认证器标识。当指定了appName时存储前缀会变为${storagePrefix}${appName.toUpperCase()}_见 APIClient.ts例如appName: myApp时 token 存于NOCOBASE_MYAPP_TOKEN从而实现多应用间存储隔离。role 与 Cookie 的联动与其它属性不同设置role除了写入 storage还会同步写入浏览器 Cookie。源码 setRole() 调用setRoleCookie而 auth-cookie.ts 中的实现会写入形如role_appNamerole的 CookieSameSiteLaxHTTPS 下附加Secure并支持通过Path与部署的 public path 对齐。当角色被置空登出时该 Cookie 会以Max-Age0被立即清除。测试用例 api-client.test.ts 验证了带appName命名空间的角色 Cookie 写入与清除行为。token 变更事件设置token时Auth还会通过api.app.eventBus派发一个auth:tokenChanged的自定义事件Auth.ts事件detail中包含新的token与authenticator。这意味着应用其它模块可以监听该事件实时响应登录态变化例如刷新用户信息或跳转页面。请求拦截器自动附加认证请求头Auth的核心价值之一是middleware拦截器Auth.ts在每次请求发出前自动附加以下请求头条件附加的请求头值已设置localeX-Locale当前语言已设置roleX-Role当前角色已设置authenticator且未显式指定X-Authenticator认证器标识已设置token且未显式指定AuthorizationBearer token非安全方法非get/head/options且有 CSRF CookieX-CSRF-TokenCookie 中的csrfToken其中SAFE_METHODS new Set([get, head, options])即只有写操作post、put、delete等才会附加 CSRF Token这是 headers.ts 中hasHeaderValue与auth-cookie.ts中getAuthCookieValue(csrfToken, appName)配合实现的防重放保护。测试用例 api-client.test.ts 中的syncCookies用例验证了拦截器行为设置 token 后发出的请求携带Authorization: Bearer 123请求头。由于这些请求头在每个请求上自动附加业务代码无需手动拼接认证信息只需确保登录后token等属性已正确写入即可。类方法详解signIn()用户登录签名async signIn(values: any, authenticator?: string): PromiseAxiosResponseany参数参数名类型描述valuesany登录接口请求参数如{ email, password }或{ username, password }authenticatorstring登录使用的认证器标识如basic、password或第三方认证器名称源码行为Auth.tssignIn会向auth:signIn动作发起 POST 请求并在请求头中携带X-Authenticator指定认证器。请求成功后从响应体response.data.data中取出服务端签发的token依次执行this.setAuthenticator(authenticator)将认证器标识持久化this.setToken(data?.token)将 token 持久化并触发auth:tokenChanged事件。因此登录成功后后续所有请求都会通过拦截器自动携带Authorization: Bearer token与X-Authenticator。测试用例api-client.test.ts完整验证了这一流程mock 返回{ data: { token: 123 } }后api.auth.getToken()与localStorage中的值均为123。典型用法const response await api.auth.signIn( { email: adminnocobase.com, password: your-password }, basic, ); // 登录成功后 token 已自动持久化可直接发起业务请求 const data await api.resource(users).list();signUp()用户注册签名async signUp(values: any, authenticator?: string): PromiseAxiosResponseany参数参数名类型描述valuesany注册接口请求参数如邮箱、密码、昵称等authenticatorstring注册使用的认证器标识signUp向auth:signUp动作发起 POST 请求Auth.ts。与signIn不同signUp本身不会自动写入 token——是否需要在注册后自动登录取决于具体业务可注册后调用signIn完成登录态建立。signOut()注销登录签名async signOut(values: any, authenticator?: string): PromiseAxiosResponseany参数参数名类型描述valuesany注销接口请求参数authenticatorstring注销使用的认证器标识signOut向auth:signOut动作发起 POST 请求Auth.ts并在请求完成后执行清理this.setToken(null)清除本地 tokenthis.setRole(null)清除角色 storage 与角色 Cookiethis.setAuthenticator(null)清除认证器标识。从而完整移除本地登录态。业务中通常会在退出登录按钮中调用它随后跳转到登录页。其它实用方法文档之外的补充除了官方文档列出的三个方法源码还提供了四个与密码找回、登录态同步相关的方法方法请求动作说明syncCookies()auth:syncCookies已有 token 时调用用于将登录态同步到 Cookie多端/多应用场景无 token 时直接返回undefinedlostPassword(values)auth:lostPassword发送找回密码邮件自动从当前 URL 提取baseURL与认证器查询参数resetPassword(values)auth:resetPassword重置密码checkResetToken(values)auth:checkResetToken校验重置密码用的 token 是否有效这些方法均以auth:action的动作命名发起请求与 NocoBase 服务端动作路由一一对应。自定义 Auth 子类接入自有认证协议APIClient的构造参数支持authClass允许你用自定义类替换默认Auth实现。官方测试给出了一个标准范例api-client.test.tsimport { APIClient, Auth } from nocobase/sdk; class TestAuth extends Auth { async signIn(values: any) { const response await this.api.request({ method: post, url: auth:test, data: values, }); const data response?.data?.data; this.setAuthenticator(test); this.setToken(data?.token); return response; } } const api new APIClient({ baseURL: https://localhost:8000/api, authClass: TestAuth, });子类可以覆写signIn、signUp、signOut等任意方法并复用基类的setToken、setAuthenticator、setRole等能力。测试断言api.auth是TestAuth的实例且登录后NOCOBASE_TOKEN与NOCOBASE_AUTH均被正确写入证明扩展机制完整可用。注意自定义子类必须调用基类构造函数或在内部自行注册拦截器否则请求头自动附加能力将失效。多应用与 Token 共享APIClient提供appName与shareToken两个配置项用于多应用场景appName为当前应用指定存储命名空间使各应用的 token、角色等互不干扰shareToken设为true时token会统一读写到基础前缀baseStoragePrefix之下实现多个应用共享同一登录态。相关逻辑位于 Storage.ts 的LocalStorage实现当shareToken key token时读写使用baseStoragePrefix拼接的 key。测试用例api-client.test.ts验证了两个不同appName的APIClient在shareToken: true时后一个实例能读到前一个实例写入的 token。APIClient还支持storageType: sessionStorage | memory来切换存储介质——sessionStorage适合关闭标签页即退出登录的场景memory则完全不落盘适合测试或敏感环境。源码级验证从测试用例看完整链路NocoBase SDK 的测试目录 提供了对Auth行为的直接验证signIn 全链路api-client.test.tsmockauth:signIn响应后断言 token 与 authenticator 均已写入内存与 localStoragesyncCookies 与拦截器api-client.test.ts断言请求头为Bearer 123确认Authorization自动附加逻辑角色 Cookieapi-client.test.ts断言角色 Cookie 的写入与清除存储命名Storage.test.ts验证toUpperCase的 key 拼接规则与localStorage/sessionStorage读写。在客户端应用中apiClient.auth.token也被广泛用于判断登录态例如 client-v2/Application.tsx 与 client-v2/BaseApplication.tsx 都会读取auth.token来初始化带认证的 WebSocket 连接等场景。这说明Auth不仅是 API 调用的认证层也是整个客户端登录态的数据源。小结Auth是 NocoBase 前端 SDK 的认证核心随APIClient自动实例化并通过请求拦截器为所有请求附加X-Locale、X-Role、X-Authenticator、Authorization与X-CSRF-Token四个实例属性locale、role、token、authenticator分别持久化到 localStoragekey 为NOCOBASE_*其中role额外同步 Cookietoken变更会派发auth:tokenChanged事件signIn登录成功后自动持久化 token 与认证器signUp仅注册、signOut完整清理本地登录态另有syncCookies、lostPassword、resetPassword、checkResetToken等配套方法通过authClass可扩展自定义认证协议通过appName/shareToken/storageType可控制多应用隔离、token 共享与存储介质以上全部行为均有 packages/core/sdk/src/Auth.ts、packages/core/sdk/src/APIClient.ts、packages/core/sdk/src/Storage.ts 及 packages/core/sdk/src/tests/api-client.test.ts 等源码与测试背书可在仓库中进一步查阅。关于认证器Authenticator的概念与配置可继续阅读 用户认证文档。【免费下载链接】nocobaseNocoBase is an open-source AI no-code platform for building business systems fast. Instead of generating everything from scratch, AI works on top of production-proven infrastructure and a WYSIWYG no-code interface, so you get both speed and reliability.项目地址: https://gitcode.com/GitHub_Trending/no/nocobase创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考