在 Refine v5 中集成 NestJS CRUDrefinedev/nestjsx-crud 数据提供器完整指南【免费下载链接】refineA React Framework for building internal tools, admin panels, dashboards B2B apps with unmatched flexibility.项目地址: https://gitcode.com/GitHub_Trending/re/refineRefine 官方为基于 Nest.js CRUD 构建的 RESTful API 提供了开箱即用的数据提供器refinedev/nestjsx-crud。本指南将以documentation/docs/data/packages/nestjsx-crud/index.md为骨架结合仓库内packages/nestjsx-crud的完整源码实现与测试用例带你从安装、挂载、认证到分页/排序/过滤/联表查询的底层映射原理一次性掌握在 Refine 应用中对接 NestJS CRUD 后端的完整方案。背景Refine 数据提供器与 NestJS CRUD 的对接点Refine 通过「数据提供器Data Provider」抽象层与后端通信统一了getList、getOne、create、update、deleteOne、custom等数据方法。而 NestJS CRUD 是 Nest.js 生态中用于快速构建 CRUD RESTful API 的模块它基于nestjsx/crud-request提供了一套强大的查询语法s搜索、filter过滤、sort排序、join联表、page/limit/offset分页。refinedev/nestjsx-crud的职责就是把 Refine 的通用数据请求翻译成 NestJS CRUD 能识别的查询串。该包以axios作为 HTTP 客户端源码见 packages/nestjsx-crud/package.json依赖axios ^1.11.0与nestjsx/crud-request ^5.0.0-alpha.3并以refinedev/core ^5.0.0为 peer 依赖适配 Refine v5。安装在 Refine 项目中安装数据提供器npm install refinedev/nestjsx-crud # 或使用 pnpm / yarn pnpm add refinedev/nestjsx-crud关于 Refine 中的数据获取模式可参考 Data Fetching 指南。快速上手创建并挂载数据提供器将你的 API 地址传入dataProvider函数即可得到一个完整的、满足RequiredDataProvider契约的数据提供器源码见 packages/nestjsx-crud/src/provider.tsimport Refine from refinedev/core; import dataProvider from refinedev/nestjsx-crud; const App () ( Refine dataProvider{dataProvider(API_URL)} {/* ... */} /Refine );其中API_URL替换为你的 NestJS CRUD API 根地址例如仓库示例中使用的https://api.nestjsx-crud.refine.dev见 examples/data-provider-nestjsx-crud/src/App.tsx。dataProvider的第二个可选参数是自定义的AxiosInstance不传时默认使用包内导出的axiosInstance。请求是如何被构造的数据提供器底层原理为了让读者做到「知其然更知其所以然」这里结合源码剖析核心方法。getList查询串的组装流水线getList依次调用四个工具函数来构造nestjsx/crud-request的RequestQueryBuilder见 provider.tslet query RequestQueryBuilder.create(); query handleFilter(query, filters); query handleJoin(query, meta?.join); query handlePagination(query, pagination); query handleSort(query, sorters); const { data } await httpClient.get(${url}?${query.query()});过滤handleFilter将 Refine 的CrudFilters递归转换为 CRUD 的搜索条件对象SCondition顶层用and/or组合叶子节点映射到具体字段与操作符见 src/utils/handleFilter.ts。联表handleJoin将meta?.join透传给query.setJoin(join)见 src/utils/handleJoin.ts。分页handlePagination仅在mode server时生效默认currentPage 1、pageSize 10通过setLimit(pageSize).setPage(currentPage).setOffset((currentPage - 1) * pageSize)生成limit/page/offset参数若使用mode: client则不做服务端分页见 src/utils/handlePagination.ts。排序handleSort将排序字段与顺序asc/desc转为大写构造成sortBy数组见 src/utils/handleSort.ts。返回值兼容两种响应形态当 API 未启用分页返回纯数组时total取数组长度当返回{ data, total }分页结构时直接透传见 provider.ts。其余方法的请求形态方法HTTP 请求说明getManyGET /{resource}?filterid$in...使用CondOperator.IN对ids建id过滤条件并支持meta?.joincreatePOST /{resource}提交variablescreateManyPOST /{resource}/bulk以{ bulk: variables }批量创建updatePATCH /{resource}/{id}局部更新updateMany并发PATCH /{resource}/{id}逐个更新收集错误getOneGET /{resource}/{id}?join...支持meta?.joindeleteOneDELETE /{resource}/{id}单条删除deleteMany并发DELETE /{resource}/{id}批量删除custom按method分发get/post/put/patch/delete额外支持meta.join、filters、sorters与自定义query/headers/payload以上实现细节均可在 packages/nestjsx-crud/src/provider.ts 中逐行核对仓库还提供了覆盖getList、getOne、create、update、deleteMany、custom等方法的 Vitest 测试见 packages/nestjsx-crud/test。认证为数据提供器注入鉴权信息当 API 需要认证时你可以通过dataProvider的第二个参数传入一个带认证头或拦截器的 axios 实例。包内默认导出的axiosInstance可直接复用也可以传入你自己的实例。方式一在登录/登出时设置 Headers利用authProvider的生命周期在登录时写入Authorization头登出时清除import { Refine, AuthProvider } from refinedev/core; /** * 我们使用包导出的 axiosInstance * 你也可以传入自定义配置的实例。 */ import dataProvider, { axiosInstance } from refinedev/nestjsx-crud; const authProvider: AuthProvider { login: async () { // ... // 用户登录后设置 Authorization 头 axiosInstance.defaults.headers.common[ Authorization ] Bearer ${localStorage.getItem(token)}; }, logout: async () { // ... // 用户登出时移除 Authorization 头 axiosInstance.defaults.headers.common[Authorization] undefined; }, // ... }; const App () { return ( Refine dataProvider{dataProvider(API_URL, axiosInstance)} authProvider{authProvider} {/* ... */} /Refine ); };方式二使用 axios 请求拦截器更灵活的做法是在拦截器里动态读取 token 并注入请求头适合 token 刷新或从 storage 读取的场景import { Refine, AuthProvider } from refinedev/core; /** * 我们使用包导出的 axiosInstance * 你也可以传入自定义配置的实例。 */ import dataProvider, { axiosInstance } from refinedev/nestjsx-crud; axiosInstance.interceptors.request.use( (config) { // ... // 若 localStorage 中存在 token则设置 Authorization 头 const token localStorage.getItem(token); if (token) { config.headers[Authorization] Bearer ${token}; } return config; }, (error) { return Promise.reject(error); }, ); const App () { return ( Refine dataProvider{dataProvider(API_URL, axiosInstance)} {/* ... */} /Refine ); };两种方式的完整示例均出自 documentation/docs/data/packages/nestjsx-crud/index.md可直接复制运行。默认 axiosInstance 做了什么包内默认实例在 src/utils/axios.ts 中创建它注册了一个响应拦截器把 axios 错误统一转换为 Refine 的HttpError形态——message取error.response?.data?.messagestatusCode取 HTTP 状态码。这意味着即使你不做任何错误处理Refine 的useNotification、useMutation也能拿到结构化的错误信息。进阶操作符、过滤与字段级错误映射操作符映射表Refine 的过滤操作符会被 src/utils/mapOperator.ts 映射为 NestJS CRUD 的CondOperatorRefine 操作符NestJS CRUD 操作符eq/ne$eq/$nelt/gt/lte/gte$lt/$gt/$lte/$gtein/nin$in/$notincontains/ncontains$contL/$exclL忽略大小写包含/排除containss/ncontainss$cont/$excl区分大小写null/nnull$isnull/$notnullstartswith/startswiths$startsL/$startsendswith/endswiths$endsL/$endsbetween$betweenand/or$and/$or未识别的操作符默认回退为$eq。对应行为由 src/utils/mapOperator.spec.ts 等测试覆盖验证。使用meta.join联表查询getList、getMany、getOne、custom都支持通过meta.join让 NestJS CRUD 一次性联表返回关联数据。例如import { useTable } from refinedev/antd; const { tableQueryResult } useTable({ meta: { join: { field: category, // 关联字段 select: [id, title], }, }, });meta.join会被handleJoin原样传给query.setJoin(join)见 src/utils/handleJoin.ts支持单个对象、数组以及fieldselect的完整配置形态。服务端字段级错误归一化NestJS CRUD 的校验错误以「字段名 空格 错误消息」的字符串数组返回例如[title should not be empty]。包内的transformErrorMessages见 src/utils/transformErrorMessages.ts会按第一个空格切分字段名聚合成{ [field]: string[] }结构transformHttpError见 src/utils/transformHttpError.ts再将其组装为{ statusCode, message, errors }的HttpError。这正是 Refine 表单如 antd 的useForm能自动把错误绑定到对应字段输入框的底层支撑。完整示例data-provider-nestjsx-crud仓库在 examples/data-provider-nestjsx-crud 提供了可直接运行的完整示例它基于 antd UI、refinedev/react-router路由注册了posts与categories两个资源并挂载了dataProvider(API_URL)import dataProvider from refinedev/nestjsx-crud; const API_URL https://api.nestjsx-crud.refine.dev; const App: React.FC () { return ( BrowserRouter ConfigProvider theme{RefineThemes.Blue} AntdApp Refine dataProvider{dataProvider(API_URL)} routerProvider{routerProvider} resources{[ { name: posts, list: /posts, create: /posts/create, edit: /posts/edit/:id, show: /posts/show/:id, }, { name: categories, list: /categories, create: /categories/create, edit: /categories/edit/:id, }, ]} notificationProvider{useNotificationProvider} options{{ syncWithLocation: true, warnWhenUnsavedChanges: true, }} {/* 路由与页面 */} /Refine /AntdApp /ConfigProvider /BrowserRouter ); };完整代码见 examples/data-provider-nestjsx-crud/src/App.tsx。运行方式cd examples/data-provider-nestjsx-crud pnpm install pnpm dev示例中的列表页即可体验服务端分页、排序、筛选如按status过滤、联表展示分类名等 NestJS CRUD 能力与 Refine 的useTable、useList等 Hook 无缝衔接。小结refinedev/nestjsx-crud让 Refine 应用与 NestJS CRUD 后端之间实现了「零胶水代码」的对接安装包、传 API 地址、按需注入认证 axios 实例即可获得完整的数据能力。其内部通过RequestQueryBuilder把 Refine 的过滤/排序/分页/联表请求精确翻译为 NestJS CRUD 查询语法并通过响应拦截器与错误转换器保证错误信息在 Refine 生态内结构化流转。若想深入源码建议从 provider.ts 与 src/utils 目录入手配合 test 目录 中的用例对照阅读可快速掌握每一个映射细节。【免费下载链接】refineA React Framework for building internal tools, admin panels, dashboards B2B apps with unmatched flexibility.项目地址: https://gitcode.com/GitHub_Trending/re/refine创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
在 Refine v5 中集成 NestJS CRUD：@refinedev/nestjsx-crud 数据提供器完整指南
在 Refine v5 中集成 NestJS CRUDrefinedev/nestjsx-crud 数据提供器完整指南【免费下载链接】refineA React Framework for building internal tools, admin panels, dashboards B2B apps with unmatched flexibility.项目地址: https://gitcode.com/GitHub_Trending/re/refineRefine 官方为基于 Nest.js CRUD 构建的 RESTful API 提供了开箱即用的数据提供器refinedev/nestjsx-crud。本指南将以documentation/docs/data/packages/nestjsx-crud/index.md为骨架结合仓库内packages/nestjsx-crud的完整源码实现与测试用例带你从安装、挂载、认证到分页/排序/过滤/联表查询的底层映射原理一次性掌握在 Refine 应用中对接 NestJS CRUD 后端的完整方案。背景Refine 数据提供器与 NestJS CRUD 的对接点Refine 通过「数据提供器Data Provider」抽象层与后端通信统一了getList、getOne、create、update、deleteOne、custom等数据方法。而 NestJS CRUD 是 Nest.js 生态中用于快速构建 CRUD RESTful API 的模块它基于nestjsx/crud-request提供了一套强大的查询语法s搜索、filter过滤、sort排序、join联表、page/limit/offset分页。refinedev/nestjsx-crud的职责就是把 Refine 的通用数据请求翻译成 NestJS CRUD 能识别的查询串。该包以axios作为 HTTP 客户端源码见 packages/nestjsx-crud/package.json依赖axios ^1.11.0与nestjsx/crud-request ^5.0.0-alpha.3并以refinedev/core ^5.0.0为 peer 依赖适配 Refine v5。安装在 Refine 项目中安装数据提供器npm install refinedev/nestjsx-crud # 或使用 pnpm / yarn pnpm add refinedev/nestjsx-crud关于 Refine 中的数据获取模式可参考 Data Fetching 指南。快速上手创建并挂载数据提供器将你的 API 地址传入dataProvider函数即可得到一个完整的、满足RequiredDataProvider契约的数据提供器源码见 packages/nestjsx-crud/src/provider.tsimport Refine from refinedev/core; import dataProvider from refinedev/nestjsx-crud; const App () ( Refine dataProvider{dataProvider(API_URL)} {/* ... */} /Refine );其中API_URL替换为你的 NestJS CRUD API 根地址例如仓库示例中使用的https://api.nestjsx-crud.refine.dev见 examples/data-provider-nestjsx-crud/src/App.tsx。dataProvider的第二个可选参数是自定义的AxiosInstance不传时默认使用包内导出的axiosInstance。请求是如何被构造的数据提供器底层原理为了让读者做到「知其然更知其所以然」这里结合源码剖析核心方法。getList查询串的组装流水线getList依次调用四个工具函数来构造nestjsx/crud-request的RequestQueryBuilder见 provider.tslet query RequestQueryBuilder.create(); query handleFilter(query, filters); query handleJoin(query, meta?.join); query handlePagination(query, pagination); query handleSort(query, sorters); const { data } await httpClient.get(${url}?${query.query()});过滤handleFilter将 Refine 的CrudFilters递归转换为 CRUD 的搜索条件对象SCondition顶层用and/or组合叶子节点映射到具体字段与操作符见 src/utils/handleFilter.ts。联表handleJoin将meta?.join透传给query.setJoin(join)见 src/utils/handleJoin.ts。分页handlePagination仅在mode server时生效默认currentPage 1、pageSize 10通过setLimit(pageSize).setPage(currentPage).setOffset((currentPage - 1) * pageSize)生成limit/page/offset参数若使用mode: client则不做服务端分页见 src/utils/handlePagination.ts。排序handleSort将排序字段与顺序asc/desc转为大写构造成sortBy数组见 src/utils/handleSort.ts。返回值兼容两种响应形态当 API 未启用分页返回纯数组时total取数组长度当返回{ data, total }分页结构时直接透传见 provider.ts。其余方法的请求形态方法HTTP 请求说明getManyGET /{resource}?filterid$in...使用CondOperator.IN对ids建id过滤条件并支持meta?.joincreatePOST /{resource}提交variablescreateManyPOST /{resource}/bulk以{ bulk: variables }批量创建updatePATCH /{resource}/{id}局部更新updateMany并发PATCH /{resource}/{id}逐个更新收集错误getOneGET /{resource}/{id}?join...支持meta?.joindeleteOneDELETE /{resource}/{id}单条删除deleteMany并发DELETE /{resource}/{id}批量删除custom按method分发get/post/put/patch/delete额外支持meta.join、filters、sorters与自定义query/headers/payload以上实现细节均可在 packages/nestjsx-crud/src/provider.ts 中逐行核对仓库还提供了覆盖getList、getOne、create、update、deleteMany、custom等方法的 Vitest 测试见 packages/nestjsx-crud/test。认证为数据提供器注入鉴权信息当 API 需要认证时你可以通过dataProvider的第二个参数传入一个带认证头或拦截器的 axios 实例。包内默认导出的axiosInstance可直接复用也可以传入你自己的实例。方式一在登录/登出时设置 Headers利用authProvider的生命周期在登录时写入Authorization头登出时清除import { Refine, AuthProvider } from refinedev/core; /** * 我们使用包导出的 axiosInstance * 你也可以传入自定义配置的实例。 */ import dataProvider, { axiosInstance } from refinedev/nestjsx-crud; const authProvider: AuthProvider { login: async () { // ... // 用户登录后设置 Authorization 头 axiosInstance.defaults.headers.common[ Authorization ] Bearer ${localStorage.getItem(token)}; }, logout: async () { // ... // 用户登出时移除 Authorization 头 axiosInstance.defaults.headers.common[Authorization] undefined; }, // ... }; const App () { return ( Refine dataProvider{dataProvider(API_URL, axiosInstance)} authProvider{authProvider} {/* ... */} /Refine ); };方式二使用 axios 请求拦截器更灵活的做法是在拦截器里动态读取 token 并注入请求头适合 token 刷新或从 storage 读取的场景import { Refine, AuthProvider } from refinedev/core; /** * 我们使用包导出的 axiosInstance * 你也可以传入自定义配置的实例。 */ import dataProvider, { axiosInstance } from refinedev/nestjsx-crud; axiosInstance.interceptors.request.use( (config) { // ... // 若 localStorage 中存在 token则设置 Authorization 头 const token localStorage.getItem(token); if (token) { config.headers[Authorization] Bearer ${token}; } return config; }, (error) { return Promise.reject(error); }, ); const App () { return ( Refine dataProvider{dataProvider(API_URL, axiosInstance)} {/* ... */} /Refine ); };两种方式的完整示例均出自 documentation/docs/data/packages/nestjsx-crud/index.md可直接复制运行。默认 axiosInstance 做了什么包内默认实例在 src/utils/axios.ts 中创建它注册了一个响应拦截器把 axios 错误统一转换为 Refine 的HttpError形态——message取error.response?.data?.messagestatusCode取 HTTP 状态码。这意味着即使你不做任何错误处理Refine 的useNotification、useMutation也能拿到结构化的错误信息。进阶操作符、过滤与字段级错误映射操作符映射表Refine 的过滤操作符会被 src/utils/mapOperator.ts 映射为 NestJS CRUD 的CondOperatorRefine 操作符NestJS CRUD 操作符eq/ne$eq/$nelt/gt/lte/gte$lt/$gt/$lte/$gtein/nin$in/$notincontains/ncontains$contL/$exclL忽略大小写包含/排除containss/ncontainss$cont/$excl区分大小写null/nnull$isnull/$notnullstartswith/startswiths$startsL/$startsendswith/endswiths$endsL/$endsbetween$betweenand/or$and/$or未识别的操作符默认回退为$eq。对应行为由 src/utils/mapOperator.spec.ts 等测试覆盖验证。使用meta.join联表查询getList、getMany、getOne、custom都支持通过meta.join让 NestJS CRUD 一次性联表返回关联数据。例如import { useTable } from refinedev/antd; const { tableQueryResult } useTable({ meta: { join: { field: category, // 关联字段 select: [id, title], }, }, });meta.join会被handleJoin原样传给query.setJoin(join)见 src/utils/handleJoin.ts支持单个对象、数组以及fieldselect的完整配置形态。服务端字段级错误归一化NestJS CRUD 的校验错误以「字段名 空格 错误消息」的字符串数组返回例如[title should not be empty]。包内的transformErrorMessages见 src/utils/transformErrorMessages.ts会按第一个空格切分字段名聚合成{ [field]: string[] }结构transformHttpError见 src/utils/transformHttpError.ts再将其组装为{ statusCode, message, errors }的HttpError。这正是 Refine 表单如 antd 的useForm能自动把错误绑定到对应字段输入框的底层支撑。完整示例data-provider-nestjsx-crud仓库在 examples/data-provider-nestjsx-crud 提供了可直接运行的完整示例它基于 antd UI、refinedev/react-router路由注册了posts与categories两个资源并挂载了dataProvider(API_URL)import dataProvider from refinedev/nestjsx-crud; const API_URL https://api.nestjsx-crud.refine.dev; const App: React.FC () { return ( BrowserRouter ConfigProvider theme{RefineThemes.Blue} AntdApp Refine dataProvider{dataProvider(API_URL)} routerProvider{routerProvider} resources{[ { name: posts, list: /posts, create: /posts/create, edit: /posts/edit/:id, show: /posts/show/:id, }, { name: categories, list: /categories, create: /categories/create, edit: /categories/edit/:id, }, ]} notificationProvider{useNotificationProvider} options{{ syncWithLocation: true, warnWhenUnsavedChanges: true, }} {/* 路由与页面 */} /Refine /AntdApp /ConfigProvider /BrowserRouter ); };完整代码见 examples/data-provider-nestjsx-crud/src/App.tsx。运行方式cd examples/data-provider-nestjsx-crud pnpm install pnpm dev示例中的列表页即可体验服务端分页、排序、筛选如按status过滤、联表展示分类名等 NestJS CRUD 能力与 Refine 的useTable、useList等 Hook 无缝衔接。小结refinedev/nestjsx-crud让 Refine 应用与 NestJS CRUD 后端之间实现了「零胶水代码」的对接安装包、传 API 地址、按需注入认证 axios 实例即可获得完整的数据能力。其内部通过RequestQueryBuilder把 Refine 的过滤/排序/分页/联表请求精确翻译为 NestJS CRUD 查询语法并通过响应拦截器与错误转换器保证错误信息在 Refine 生态内结构化流转。若想深入源码建议从 provider.ts 与 src/utils 目录入手配合 test 目录 中的用例对照阅读可快速掌握每一个映射细节。【免费下载链接】refineA React Framework for building internal tools, admin panels, dashboards B2B apps with unmatched flexibility.项目地址: https://gitcode.com/GitHub_Trending/re/refine创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考