HOW - 前端 sdk 实践（二）- 权限 SDK

一、实践目标 - 权限 SDK

今天我们要封装一个「权限 SDK」用于 React + Rollup（或者 Vite） + TypeScript 项目，这是一个非常实用的场景，特别是在中后台系统中。

这类 SDK 通常用于：

• 获取当前用户权限信息（如菜单、按钮、资源权限等）
• 权限校验（如是否能访问页面、是否展示某个按钮）
• 提供权限判断方法或指令式组件（如 <Auth>、useAuth）

权限 SDK 要解决的问题

1. 获取用户权限数据（通常是数组，如 ['page.view', 'user.edit']）
2. 提供权限校验方法（如 hasPermission('user.edit')）
3. 提供 React Hook 和组件支持（如 useAuth()，<Auth check="user.edit" />）
4. 能根据权限隐藏/禁用页面内容或组件
5. 可扩展、类型安全、低耦合

方案设计：基于 Rollup

Rollup 是一款非常适用于 JavaScript 的模块打包工具。

目录结构建议

permission-sdk/
├── src/
│   ├── index.ts              # SDK 入口
│   ├── core/
│   │   └── permission.ts     # 权限核心方法
│   ├── react/
│   │   ├── Auth.tsx          # 权限组件
│   │   └── useAuth.ts        # 权限 Hook
│   └── types.ts              # 类型定义
├── rollup.config.ts          # 打包配置
├── package.json
├── tsconfig.json

核心逻辑示例

1. 权限存储与校验

core/permission.ts

let permissionList: string[] = [];export const setPermissions = (list: string[]) => {permissionList = list;
};export const getPermissions = () => permissionList;export const hasPermission = (key: string | string[]) => {if (Array.isArray(key)) {return key.some(k => permissionList.includes(k));}return permissionList.includes(key);
};

2. React Hook 支持

react/useAuth.ts

import { hasPermission } from '../core/permission';export const useAuth = () => {return {hasPermission,};
};

3. 权限组件封装

react/Auth.tsx

import { FC, PropsWithChildren } from 'react';
import { hasPermission } from '../core/permission';interface AuthProps {check: string | string[];fallback?: React.ReactNode;
}export const Auth: FC<PropsWithChildren<AuthProps>> = ({ check, fallback = null, children }) => {return hasPermission(check) ? <>{children}</> : <>{fallback}</>;
};

使用示例：

<Auth check="user.edit"><Button>编辑用户</Button>
</Auth>

4. SDK 统一导出

index.ts

export * from './core/permission';
export * from './react/Auth';
export * from './react/useAuth';

打包配置

rollup.config.ts

import typescript from '@rollup/plugin-typescript';
import dts from 'rollup-plugin-dts';export default [{input: 'src/index.ts',output: [{ file: 'dist/index.esm.js', format: 'esm' },{ file: 'dist/index.cjs.js', format: 'cjs' },],plugins: [typescript()],},{input: 'src/index.ts',output: { file: 'dist/index.d.ts', format: 'es' },plugins: [dts()],},
];

使用方式

在 React 项目中：

// main.tsx
import { setPermissions } from 'permission-sdk';
setPermissions(['page.view', 'user.edit']);// 页面组件
import { Auth, useAuth } from 'permission-sdk';const Page = () => {const { hasPermission } = useAuth();return (<>{hasPermission('user.edit') && <Button>编辑</Button>}<Auth check="page.view"><div>你有查看页面的权限</div></Auth></>);
};

支持拓展的点

• 自动拉取权限接口 fetchPermissions()，并结合用户登录
• 增加权限校验模式（全匹配 / 任一匹配）
• 添加权限模式（read-only, edit-only）
• 针对多个项目做微前端适配
• 权限缓存（localStorage/sessionStorage）
• 添加 debug 模式和日志输出

实践：基于现代打包工具 Vite

Vite 可能是现在前端更常用的工具，所以我们接下来会选择它来具体实践。

第一步：创建目录

同理，目录结构建议如下：

permission-sdk/
├── src/
│   ├── index.ts              # SDK 入口
│   ├── core/
│   │   └── permission.ts     # 权限核心方法
│   ├── react/
│   │   ├── Auth.tsx          # 权限组件
│   │   └── useAuth.ts        # 权限 Hook
│   └── types.ts              # 类型定义
├── vite.config.ts
├── package.json
├── tsconfig.json

第二步：初始化 SDK 包信息

在 permission-sdk/package.json 写入：

{"name": "@hg-data/permission-sdk","private": true,"version": "0.1.0","main": "dist/index.umd.js","module": "dist/index.es.js","types": "dist/index.d.ts","type": "module","scripts": {"dev": "vite","build": "tsc -b && vite build","lint": "eslint .","preview": "vite preview"},"dependencies": {"react": "^19.0.0","react-dom": "^19.0.0"},"devDependencies": {"@eslint/js": "^9.22.0","@types/react": "^19.0.10","@types/react-dom": "^19.0.4","@vitejs/plugin-react": "^4.3.4","eslint": "^9.22.0","eslint-plugin-react-hooks": "^5.2.0","eslint-plugin-react-refresh": "^0.4.19","globals": "^16.0.0","typescript": "~5.7.2","typescript-eslint": "^8.26.1","vite": "^6.3.0","vite-plugin-dts": "^4.5.3"}
}

其中 vite-plugin-dts 是另外单独 pnpm install 的，具体使用方法可阅读 vite-plugin-dts

第三步：SDK 源码结构

把前面的核心逻辑示例代码粘贴到 /permission-sdk/src/ 中，这里是结构：

• index.ts：统一导出
• core/permission.ts：权限数据和校验方法
• react/Auth.tsx：权限组件
• react/useAuth.ts：权限 Hook

第四步：tsconfig.json

permission-sdk/tsconfig.json：

{"compilerOptions": {"target": "ESNext","module": "ESNext","moduleResolution": "Node","jsx": "react-jsx","strict": true,"declaration": true,"declarationDir": "dist","outDir": "dist","esModuleInterop": true,"skipLibCheck": true},"include": ["src"]
}

上述仅做参考。

第五步：使用 Vite 打包（或用 tsup）

创建 permission-sdk/vite.config.ts：

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import path from 'path'// https://vite.dev/config/
export default defineConfig({plugins: [react()],build: {lib: {entry: path.resolve(__dirname, 'src/index.ts'),name: 'PermissionSDK',fileName: (format) => `index.${format}.js`,},rollupOptions: {external: ['react'],output: {globals: {react: 'React'}}}}
})

然后执行：

cd permission-sdk
pnpm install
pnpm build

构建产物会在 permission-sdk/dist 下输出为 ESM 和 CJS 两种格式。

---

第六步：在主项目中使用 SDK 进行调试

可以先先作为本地模块引入进行调试。参考 HOW - 项目 link 本地开发库进行调试

第七步：使用示例

// main.tsx
import { setPermissions } from 'permission-sdk';
setPermissions(['user.edit', 'dashboard.view']);// App.tsx
import { Auth, useAuth } from 'permission-sdk';function App() {const { hasPermission } = useAuth();return (<>{hasPermission('user.edit') && <button>编辑</button>}<Auth check="dashboard.view"><div>你可以看到这个页面内容</div></Auth></>);
}