# @djangocfg/api 中文文档

规范地址：https://npmcn.com/package/%40djangocfg/api/

版本：2\.1\.655
npm 元数据更新时间：2026-11-12T12:33:56.789Z
中文译文更新时间：2026-11-12T12:10:01.205Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40djangocfg/api
原文对照：https://npmcn.com/package/%40djangocfg/api/?lang=original
项目主页：https://djangocfg.com/
源码仓库：https://github.com/markolofsen/django-cfg

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：6.6 MB，396 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：swr ^2\.3\.7，zod ^4\.3\.6，next ^16\.4\.5，react ^19\.0\.0，consola ^3\.4\.2，p-retry ^7\.0\.0
- 首次发布：2025-10-13T00:46:50.035Z
- 最新版本发布：2026-11-12T12:33:56.545Z
- 近 30 天下载量：18939（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：672（近 12 个月 630 个）

## 中文简介

自动生成 TypeScript API 客户端,带有 React shooks, SWR 集成和 Zod 验证 Django REST 框架后端

## 安装

```sh
npm install @djangocfg/api
```

也可以使用：`pnpm add @djangocfg/api`、`yarn add @djangocfg/api`、`bun add @djangocfg/api`

## README

# 翻译:

DjangoCFG应用程序的Type-seafe API客户端和认证系统.

## 安装

```bash
pnpm add @djangocfg/api
```

## 条目点

| 条目 | 导入 | 说明 |
| --- | --- | --- |
| **主要** | `@djangocfg/api` | API 类、类型、取取器、计划 |
| **认证** | `@djangocfg/api/auth` | 认证提供者、钩子、公用事业 |
| **Auth 服务器** | `@djangocfg/api/auth/server` | Next.js 代理中间软件 |
| **存储** | `@djangocfg/api/storage` | Cookie/ storage 密钥; 单签入帮助器(`safeNext`, (中文(简体) ), `deriveAuthHost`, (中文(简体) ), `buildSsoLoginUrl`(中文(简体) ) |
| **客户** | `@djangocfg/api/clients` | 预配置的 API 实例 |

## 生成的 API 类

每个 OpenAPI 标记一个类 。 直接导入并调用静态方法 :

```typescript
import {
  CfgAccounts,          // OTP login
  CfgAccountsProfile,   // Profile CRUD
  CfgAccountsOauth,     // GitHub OAuth
  CfgAccountsAuth,      // Token refresh
  CfgAccountsApiKey,    // API key management
  CfgTotp,              // TOTP devices / disable
  CfgTotpSetup,         // TOTP setup / confirm
  CfgTotpVerify,        // TOTP verify / backup
  CfgTotpBackupCodes,   // Backup codes
} from '@djangocfg/api';

// OTP login
const result = await CfgAccounts.cfgAccountsOtpVerifyCreate({
  body: { identifier, otp },
});

// Profile
const profile = await CfgAccountsProfile.cfgAccountsProfileRetrieve();

// Token refresh
const tokens = await CfgAccountsAuth.cfgAccountsTokenRefreshCreate({
  body: { refresh },
});
```

## Auth 模块

```tsx
import { AuthProvider, useAuth } from '@djangocfg/api/auth';

// Provider
<AuthProvider config={{ routes: { auth: '/auth', defaultCallback: '/private' } }}>
  {children}
</AuthProvider>

// Hook
const { user, isAuthenticated, requestOTP, verifyOTP, logout } = useAuth();
```

### Auth 钩子

```typescript
import {
  useAuth,              // Main auth context
  useAuthGuard,         // Route protection
  useAuthForm,          // OTP form state machine
  useOAuthLogin,        // GitHub / Google OAuth
  useOAuthProviders,    // providers enabled on the server
  useTwoFactor,         // 2FA verification
  useTwoFactorSetup,    // 2FA setup flow
  useTwoFactorStatus,   // 2FA status / disable
  useDeleteAccount,     // Account deletion
} from '@djangocfg/api/auth';
```

### 警卫解决者

"spinner vs referred vs compare"的决定是纯的,可以单独检验的. `useAuthGuard` (和 `@djangocfg/layouts`' `PrivateLayout`只是电线反应状态 纳入这些:

```typescript
import {
  resolveGuardIsLoading,      // show the preloader?
  shouldRedirectToAuth,       // no session → send to the auth form
  isForbidden,                // signed in, but lacks the required privilege
  resolveGuardIsAuthenticated,
  type GuardInput,
} from '@djangocfg/api/auth';
```

`GuardInput` 角色门可选两个字段 : `requireStaff` (单位:千美元) 路线需要工作人员/管理人员)和 `isAdminUser` (从) `useAuth()` - 那个 `is_staff || is_superuser` 折,从来一旗.

`isForbidden` 是故意的,这是故意的 **没有** 重定向条件:会话为 有效, 因此认证形式无法修正, 重定向会循环保存的 URL (中文(简体) ). 换成一个不同的"未经授权"状态. `resolveGuardIsLoading` 返回时 `false` 曾经禁止,所以预装机 从来没有旋转它.

## 单一登录主机

`<AuthProvider config={{ sso: true }}>` (或 `BaseApp auth={{ sso: true }}`制造( ) `auth.<apex>` 唯一的登录页面 每个子域: 追随者以 `?next=<url>` 他们将被派去教化众人 他们。 会话是共享的 cookie 组合在 `.<apex>`关闭,除非启动,并关闭 `localhost` (一个控制台线). 中间软件和客户端的纯助手在其中 `@djangocfg/api/storage`数字 : `safeNext` (唯一的大门用于 `next`, (中文(简体) ), `deriveAuthHost`, (中文(简体) ), `resolveSso`, (中文(简体) ), `buildSsoLoginUrl`。 。 。 . `useAuth().sso` 报告情况。 细节 : [`@docs/AUTHENTICATION.md`](https://npmcn.com/package/%40djangocfg/api/@docs/AUTHENTICATION.md#single-sign-in-host-auth-sso-true)。 。 。 .

## 存储密钥

每个浏览器存储键是 `cfg.<area>.<name>` (框架)或 `<owner>.<area>.<name>` (应用). 使用注册簿, 绝不是字面或生字 `localStorage`数字 :

```ts
import { CFG_KEYS, cfgStorage, createStorage } from '@djangocfg/api/storage';

cfgStorage.read(CFG_KEYS.email.key);
cfgStorage.clearAll(); // sign-out: removes personal keys

const storage = createStorage('kino');
storage.writeJSON(storage.key('player', 'volume'), 0.4);
```

旧密钥名称没有迁移 。 完整的规则,关键列表和交叉tabab行为: [`@docs/STORAGE_KEYS.md`](https://npmcn.com/package/%40djangocfg/api/@docs/STORAGE_KEYS.md)。 。 。 .

## 托肯存储

代号活在共享中 `auth` 存储( 默认本地Storage, 可切换) 饼干:

```typescript
import { auth } from '@djangocfg/api';

auth.getToken();              // current access token
auth.setStorageMode('cookie'); // SSR-readable cookie instead of localStorage
```

## 日志——意识到角色的动词

全体 `@djangocfg/*` consola loggers 读取了一个全局运行时级别, 所以控制台 对终端用户来说是干净的,对管理员/devs来说是动词——如大型SaaS应用.

```typescript
import { applyRoleLogPolicy, setLogLevel } from '@djangocfg/api';

// Usually automatic: AuthProvider calls this on login/logout.
// admin (is_staff/is_superuser) or dev → debug; prod regular user → errors only.
applyRoleLogPolicy({ isAdmin: user?.is_staff || user?.is_superuser });

// Manual override (0 silent · 1 error · 2 warn · 3 info · 4 debug · 5 trace):
setLogLevel(0);
```

错误仍然流到 `@djangocfg/devtools` 无论控制台级别如何,所以 事件仍然不可诊断.

## 信封旗帜

`@djangocfg/api` 是最小的共享软件包,所以 env 旗帜住在这里( 单 真相来源:

```typescript
import { isDev, isProd, isBrowser, isStaticBuild } from '@djangocfg/api';
```

## 类型命名空间

```typescript
import type { AccountsTypes, TotpTypes } from '@djangocfg/api';

type User = AccountsTypes.User;
type Device = TotpTypes.TotpDevice;
```

## 服务器中端软件

```typescript
// middleware.ts
import { proxyMiddleware } from '@djangocfg/api/auth/server';

export function middleware(request: NextRequest) {
  return proxyMiddleware(request);
}

export const config = {
  matcher: ['/media/:path*', '/api/:path*'],
};
```

## 环境

```bash
NEXT_PUBLIC_API_URL=http://localhost:8000
```

## 再生成客户端

```bash
# From django solution directory
make api
```

## 常见问题

### @djangocfg/api 是什么？

自动生成 TypeScript API 客户端,带有 React shooks, SWR 集成和 Zod 验证 Django REST 框架后端

### 如何安装 @djangocfg/api？

在项目目录运行 npm install @djangocfg/api，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：swr（^2\.3\.7）、zod（^4\.3\.6）、next（^16\.4\.5）、react（^19\.0\.0）、consola（^3\.4\.2）、p-retry（^7\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @djangocfg/api 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @djangocfg/api 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @djangocfg/api 可以商用吗？

@djangocfg/api 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @djangocfg/api 的下载量有多少？

根据 npm 官方下载统计，@djangocfg/api 在 2026/10/13 – 2026/11/11 这 30 天内被下载 18,939 次，日均约 631 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @djangocfg/api 还在维护吗？

最新版本 2\.1\.655 发布于 2026/11/12（今天）；至今共发布 672 个版本，其中过去 12 个月发布了 630 个；首次发布于 2025/10/13。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。