@fbkworks/data 0.0.0-stage → 0.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/dist/backend.d.ts +28 -0
- package/dist/backend.mjs +32 -0
- package/dist/backend.mjs.map +1 -0
- package/dist/create.d.ts +21 -0
- package/dist/create.mjs +74 -0
- package/dist/create.mjs.map +1 -0
- package/dist/error.d.ts +22 -0
- package/dist/error.mjs +27 -0
- package/dist/error.mjs.map +1 -0
- package/dist/index.d.ts +9 -0
- package/dist/index.mjs +16 -0
- package/dist/index.mjs.map +1 -0
- package/dist/path.d.ts +33 -0
- package/dist/path.mjs +74 -0
- package/dist/path.mjs.map +1 -0
- package/dist/scope.d.ts +14 -0
- package/dist/scope.mjs +16 -0
- package/dist/scope.mjs.map +1 -0
- package/dist/types.d.ts +184 -0
- package/package.json +47 -3
- package/README.md +0 -3
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 54356
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
import { Backend, BackendConfig } from './types.js';
|
|
2
|
+
/**
|
|
3
|
+
* 定义一个后端的响应惯例,之后每个接口只需写自己的部分。
|
|
4
|
+
*
|
|
5
|
+
* 真实项目里一个系统通常只有 1-2 种响应形状。
|
|
6
|
+
* 没有这一层,12 个接口要重复 12 遍 `rows` / `total` / `isSuccess` ——
|
|
7
|
+
* 一次决策被摊成 12 次重复。
|
|
8
|
+
*
|
|
9
|
+
* ```ts
|
|
10
|
+
* // src/api/backend.ts —— 全项目唯一一处
|
|
11
|
+
* export const api = defineBackend({
|
|
12
|
+
* request: (url, params, signal) => http.get(url, { params, signal }).then((r) => r.data),
|
|
13
|
+
* rows: 'content',
|
|
14
|
+
* total: 'totalElements',
|
|
15
|
+
* isSuccess: (res) => res.code === 200,
|
|
16
|
+
* errorMessage: (res) => res.msg,
|
|
17
|
+
* scope: 'server-filtered',
|
|
18
|
+
* })
|
|
19
|
+
*
|
|
20
|
+
* // src/api/order.ts —— 每个接口只剩自己的信息
|
|
21
|
+
* export const fetchOrders = api.page('/api/order/list', { feature: 'order.list' })
|
|
22
|
+
* ```
|
|
23
|
+
*
|
|
24
|
+
* **刻意不提供 `presets: 'spring'` 这种内置预设。**
|
|
25
|
+
* 一旦库认识 Spring,就要认识 ruoyi、GraphQL、OData……维护成本无上限。
|
|
26
|
+
* 让业务方写三个字符串,比让库猜要稳。
|
|
27
|
+
*/
|
|
28
|
+
export declare function defineBackend<TRaw = any>(config: BackendConfig<TRaw>): Backend<TRaw>;
|
package/dist/backend.mjs
ADDED
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
import { createPageRequest } from "./create.mjs";
|
|
2
|
+
function defineBackend(config) {
|
|
3
|
+
const {
|
|
4
|
+
request,
|
|
5
|
+
rows,
|
|
6
|
+
total,
|
|
7
|
+
isSuccess,
|
|
8
|
+
errorMessage,
|
|
9
|
+
scope,
|
|
10
|
+
onError,
|
|
11
|
+
mapParams
|
|
12
|
+
} = config;
|
|
13
|
+
const defaults = { rows, total, isSuccess, errorMessage, scope, onError };
|
|
14
|
+
const toParams = (query) => mapParams ? mapParams(query) : { page: query.page, pageSize: query.pageSize, ...query.params };
|
|
15
|
+
function page(pathOrFetcher, options = {}) {
|
|
16
|
+
const fetch = typeof pathOrFetcher === "function" ? pathOrFetcher : (query) => request(pathOrFetcher, toParams(query), query.signal);
|
|
17
|
+
return createPageRequest({
|
|
18
|
+
// 顺序即优先级:接口配置覆盖后端惯例
|
|
19
|
+
...defaults,
|
|
20
|
+
...options,
|
|
21
|
+
fetch
|
|
22
|
+
});
|
|
23
|
+
}
|
|
24
|
+
return {
|
|
25
|
+
page,
|
|
26
|
+
config: { request, rows, total, isSuccess, errorMessage, scope, onError, mapParams }
|
|
27
|
+
};
|
|
28
|
+
}
|
|
29
|
+
export {
|
|
30
|
+
defineBackend
|
|
31
|
+
};
|
|
32
|
+
//# sourceMappingURL=backend.mjs.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"backend.mjs","sources":["../src/backend.ts"],"sourcesContent":["import { createPageRequest } from './create'\nimport type {\n Backend,\n BackendConfig,\n CreatePageRequestConfig,\n PageFetcher,\n PageQuery,\n} from './types'\n\n/**\n * 定义一个后端的响应惯例,之后每个接口只需写自己的部分。\n *\n * 真实项目里一个系统通常只有 1-2 种响应形状。\n * 没有这一层,12 个接口要重复 12 遍 `rows` / `total` / `isSuccess` ——\n * 一次决策被摊成 12 次重复。\n *\n * ```ts\n * // src/api/backend.ts —— 全项目唯一一处\n * export const api = defineBackend({\n * request: (url, params, signal) => http.get(url, { params, signal }).then((r) => r.data),\n * rows: 'content',\n * total: 'totalElements',\n * isSuccess: (res) => res.code === 200,\n * errorMessage: (res) => res.msg,\n * scope: 'server-filtered',\n * })\n *\n * // src/api/order.ts —— 每个接口只剩自己的信息\n * export const fetchOrders = api.page('/api/order/list', { feature: 'order.list' })\n * ```\n *\n * **刻意不提供 `presets: 'spring'` 这种内置预设。**\n * 一旦库认识 Spring,就要认识 ruoyi、GraphQL、OData……维护成本无上限。\n * 让业务方写三个字符串,比让库猜要稳。\n */\nexport function defineBackend<TRaw = any>(config: BackendConfig<TRaw>): Backend<TRaw> {\n const {\n request,\n rows,\n total,\n isSuccess,\n errorMessage,\n scope,\n onError,\n mapParams,\n } = config\n\n /** 后端惯例部分。接口级配置会覆盖它 */\n const defaults = { rows, total, isSuccess, errorMessage, scope, onError }\n\n /**\n * 把 PageQuery 转成后端期望的参数名。\n *\n * 不传时直接用 `{ page, pageSize, ...params }` ——\n * 这是**约定而不是猜测**:`page` 是最中性的命名。\n * 后端用 `pageNum` 的项目显式传 mapParams,因为那是它的惯例。\n */\n const toParams = (query: PageQuery): Record<string, any> =>\n mapParams\n ? mapParams(query)\n : { page: query.page, pageSize: query.pageSize, ...query.params }\n\n function page<T = unknown>(\n pathOrFetcher: string | ((query: PageQuery) => Promise<TRaw>),\n options: Partial<Omit<CreatePageRequestConfig<TRaw, T>, 'fetch'>> = {},\n ): PageFetcher<T> {\n /* 两种形态共用同一个入口,靠参数类型区分:\n string → A 形态,用后端惯例的 request 发请求\n function → B 形态,逃生口,调用方自己发请求\n 不用两个方法名:调用处一眼能看出用的哪种,心智负担也低。 */\n const fetch =\n typeof pathOrFetcher === 'function'\n ? pathOrFetcher\n : (query: PageQuery) => request(pathOrFetcher, toParams(query), query.signal)\n\n return createPageRequest<TRaw, T>({\n // 顺序即优先级:接口配置覆盖后端惯例\n ...defaults,\n ...options,\n fetch,\n } as CreatePageRequestConfig<TRaw, T>)\n }\n\n return {\n page,\n config: { request, rows, total, isSuccess, errorMessage, scope, onError, mapParams },\n }\n}\n"],"names":[],"mappings":";AAmCO,SAAS,cAA0B,QAA4C;AACpF,QAAM;AAAA,IACJ;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,EAAA,IACE;AAGJ,QAAM,WAAW,EAAE,MAAM,OAAO,WAAW,cAAc,OAAO,QAAA;AAShE,QAAM,WAAW,CAAC,UAChB,YACI,UAAU,KAAK,IACf,EAAE,MAAM,MAAM,MAAM,UAAU,MAAM,UAAU,GAAG,MAAM,OAAA;AAE7D,WAAS,KACP,eACA,UAAoE,IACpD;AAKhB,UAAM,QACJ,OAAO,kBAAkB,aACrB,gBACA,CAAC,UAAqB,QAAQ,eAAe,SAAS,KAAK,GAAG,MAAM,MAAM;AAEhF,WAAO,kBAA2B;AAAA;AAAA,MAEhC,GAAG;AAAA,MACH,GAAG;AAAA,MACH;AAAA,IAAA,CACmC;AAAA,EACvC;AAEA,SAAO;AAAA,IACL;AAAA,IACA,QAAQ,EAAE,SAAS,MAAM,OAAO,WAAW,cAAc,OAAO,SAAS,UAAA;AAAA,EAAU;AAEvF;"}
|
package/dist/create.d.ts
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
import { CreatePageRequestConfig, PageFetcher } from './types.js';
|
|
2
|
+
/**
|
|
3
|
+
* 把「任意形状的后端响应」映射成组件库期望的 `Page<T>`。
|
|
4
|
+
*
|
|
5
|
+
* 这是 @fbkworks/data 的核心:业务方只写「字段在哪」,
|
|
6
|
+
* 不写分页、不写错误处理、不写类型转换。
|
|
7
|
+
*
|
|
8
|
+
* ```ts
|
|
9
|
+
* // ruoyi
|
|
10
|
+
* export const fetchOrders = createPageRequest({
|
|
11
|
+
* fetch: ({ page, pageSize, params, signal }) =>
|
|
12
|
+
* http.get('/api/order/list', { params: { pageNum: page, pageSize, ...params }, signal }),
|
|
13
|
+
* rows: 'rows',
|
|
14
|
+
* total: 'total',
|
|
15
|
+
* isSuccess: (res) => res.code === 200,
|
|
16
|
+
* errorMessage: (res) => res.msg,
|
|
17
|
+
* scope: 'server-filtered',
|
|
18
|
+
* })
|
|
19
|
+
* ```
|
|
20
|
+
*/
|
|
21
|
+
export declare function createPageRequest<TRaw, T = unknown>(config: CreatePageRequestConfig<TRaw, T>): PageFetcher<T>;
|
package/dist/create.mjs
ADDED
|
@@ -0,0 +1,74 @@
|
|
|
1
|
+
import { warnOnce } from "@fbkworks/shared";
|
|
2
|
+
import { FbkDataError } from "./error.mjs";
|
|
3
|
+
import { extractRows, extractTotal } from "./path.mjs";
|
|
4
|
+
function createPageRequest(config) {
|
|
5
|
+
const { fetch, rows, total, mapRow, isSuccess, errorMessage, scope, onError, feature } = config;
|
|
6
|
+
if (scope === "client-filtered") {
|
|
7
|
+
warnOnce(
|
|
8
|
+
"data-scope-client-filtered",
|
|
9
|
+
'[fbk/data] scope 为 client-filtered:数据级权限必须由服务端过滤。\n 前端隐藏不构成权限 —— 列表接口已返回全部数据,\n 任何用户都能在浏览器 Network 面板看到完整内容。\n 如果服务端确实做了过滤,请改为 scope: "server-filtered"。'
|
|
10
|
+
);
|
|
11
|
+
}
|
|
12
|
+
const report = (event) => {
|
|
13
|
+
if (!onError) return;
|
|
14
|
+
try {
|
|
15
|
+
onError(event);
|
|
16
|
+
} catch {
|
|
17
|
+
}
|
|
18
|
+
};
|
|
19
|
+
const snapshot = (query) => ({
|
|
20
|
+
page: query.page,
|
|
21
|
+
pageSize: query.pageSize,
|
|
22
|
+
sort: query.sort,
|
|
23
|
+
params: query.params
|
|
24
|
+
});
|
|
25
|
+
return async (query) => {
|
|
26
|
+
let raw;
|
|
27
|
+
try {
|
|
28
|
+
raw = await fetch(query);
|
|
29
|
+
} catch (err) {
|
|
30
|
+
const aborted = err instanceof DOMException && err.name === "AbortError";
|
|
31
|
+
if (!aborted) {
|
|
32
|
+
report({
|
|
33
|
+
source: "request",
|
|
34
|
+
feature,
|
|
35
|
+
message: err instanceof Error ? err.message : String(err),
|
|
36
|
+
cause: err,
|
|
37
|
+
context: snapshot(query)
|
|
38
|
+
});
|
|
39
|
+
}
|
|
40
|
+
throw err;
|
|
41
|
+
}
|
|
42
|
+
if (isSuccess && !isSuccess(raw)) {
|
|
43
|
+
const message = errorMessage?.(raw) ?? "请求失败(未提供 errorMessage)";
|
|
44
|
+
report({
|
|
45
|
+
source: "request",
|
|
46
|
+
feature,
|
|
47
|
+
message,
|
|
48
|
+
raw,
|
|
49
|
+
context: snapshot(query)
|
|
50
|
+
});
|
|
51
|
+
throw new FbkDataError("business", message, raw);
|
|
52
|
+
}
|
|
53
|
+
try {
|
|
54
|
+
const rawRows = extractRows(raw, rows);
|
|
55
|
+
const totalValue = total !== void 0 ? extractTotal(raw, total) : rawRows.length;
|
|
56
|
+
const list = mapRow ? rawRows.map((item, index) => mapRow(item, index)) : rawRows;
|
|
57
|
+
return { list, total: totalValue };
|
|
58
|
+
} catch (err) {
|
|
59
|
+
report({
|
|
60
|
+
source: "request",
|
|
61
|
+
feature,
|
|
62
|
+
message: err instanceof Error ? err.message : String(err),
|
|
63
|
+
raw,
|
|
64
|
+
cause: err,
|
|
65
|
+
context: snapshot(query)
|
|
66
|
+
});
|
|
67
|
+
throw err;
|
|
68
|
+
}
|
|
69
|
+
};
|
|
70
|
+
}
|
|
71
|
+
export {
|
|
72
|
+
createPageRequest
|
|
73
|
+
};
|
|
74
|
+
//# sourceMappingURL=create.mjs.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"create.mjs","sources":["../src/create.ts"],"sourcesContent":["import { warnOnce } from '@fbkworks/shared'\nimport { FbkDataError } from './error'\nimport { extractRows, extractTotal } from './path'\nimport type {\n CreatePageRequestConfig,\n Page,\n PageFetcher,\n PageQuery,\n PageRequestErrorEvent,\n} from './types'\n\n/**\n * 把「任意形状的后端响应」映射成组件库期望的 `Page<T>`。\n *\n * 这是 @fbkworks/data 的核心:业务方只写「字段在哪」,\n * 不写分页、不写错误处理、不写类型转换。\n *\n * ```ts\n * // ruoyi\n * export const fetchOrders = createPageRequest({\n * fetch: ({ page, pageSize, params, signal }) =>\n * http.get('/api/order/list', { params: { pageNum: page, pageSize, ...params }, signal }),\n * rows: 'rows',\n * total: 'total',\n * isSuccess: (res) => res.code === 200,\n * errorMessage: (res) => res.msg,\n * scope: 'server-filtered',\n * })\n * ```\n */\nexport function createPageRequest<TRaw, T = unknown>(\n config: CreatePageRequestConfig<TRaw, T>,\n): PageFetcher<T> {\n const { fetch, rows, total, mapRow, isSuccess, errorMessage, scope, onError, feature } = config\n\n /* 数据级权限提醒。\n 这不是运行时校验 —— 前端无法真正校验权限。它的价值在于\n 把「前端隐藏不构成权限」这件事,出现在写代码的那一刻。 */\n if (scope === 'client-filtered') {\n warnOnce(\n 'data-scope-client-filtered',\n '[fbk/data] scope 为 client-filtered:数据级权限必须由服务端过滤。\\n' +\n ' 前端隐藏不构成权限 —— 列表接口已返回全部数据,\\n' +\n ' 任何用户都能在浏览器 Network 面板看到完整内容。\\n' +\n ' 如果服务端确实做了过滤,请改为 scope: \"server-filtered\"。',\n )\n }\n\n /** 统一的错误上报。不上报 AbortError —— 取消不是错误 */\n const report = (event: PageRequestErrorEvent) => {\n if (!onError) return\n try {\n onError(event)\n } catch {\n /* 上报器自身抛错不能影响业务请求 */\n }\n }\n\n /** 参数快照:只留可复现所需的最小信息,避免大对象进日志 */\n const snapshot = (query: PageQuery): Record<string, unknown> => ({\n page: query.page,\n pageSize: query.pageSize,\n sort: query.sort,\n params: query.params,\n })\n\n return async (query) => {\n let raw: TRaw\n try {\n raw = await fetch(query)\n } catch (err) {\n /* 取消是正常流程(快速翻页时旧请求被 abort),\n 不能当成错误上报 —— 否则监控里全是噪音。 */\n const aborted = err instanceof DOMException && err.name === 'AbortError'\n if (!aborted) {\n report({\n source: 'request',\n feature,\n message: err instanceof Error ? err.message : String(err),\n cause: err,\n context: snapshot(query),\n })\n }\n throw err\n }\n\n /* 业务码判定。\n 有业务码的后端(ruoyi 的 code===200)如果不传 isSuccess,\n 失败响应会被当成空列表 —— 用户看到「暂无数据」,\n 而真实原因是 token 过期或参数错误。 */\n if (isSuccess && !isSuccess(raw)) {\n const message = errorMessage?.(raw) ?? '请求失败(未提供 errorMessage)'\n report({\n source: 'request',\n feature,\n message,\n raw,\n context: snapshot(query),\n })\n throw new FbkDataError('business', message, raw)\n }\n\n try {\n const rawRows = extractRows(raw, rows)\n const totalValue = total !== undefined ? extractTotal(raw, total) : rawRows.length\n\n const list = mapRow\n ? rawRows.map((item, index) => mapRow(item, index))\n : (rawRows as unknown as T[])\n\n return { list, total: totalValue } satisfies Page<T>\n } catch (err) {\n /* 路径解析失败是**开发期错误**(字段名写错),\n 但线上同样会走到这里,所以也要上报。 */\n report({\n source: 'request',\n feature,\n message: err instanceof Error ? err.message : String(err),\n raw,\n cause: err,\n context: snapshot(query),\n })\n throw err\n }\n }\n}\n"],"names":[],"mappings":";;;AA8BO,SAAS,kBACd,QACgB;AAChB,QAAM,EAAE,OAAO,MAAM,OAAO,QAAQ,WAAW,cAAc,OAAO,SAAS,QAAA,IAAY;AAKzF,MAAI,UAAU,mBAAmB;AAC/B;AAAA,MACE;AAAA,MACA;AAAA,IAAA;AAAA,EAKJ;AAGA,QAAM,SAAS,CAAC,UAAiC;AAC/C,QAAI,CAAC,QAAS;AACd,QAAI;AACF,cAAQ,KAAK;AAAA,IACf,QAAQ;AAAA,IAER;AAAA,EACF;AAGA,QAAM,WAAW,CAAC,WAA+C;AAAA,IAC/D,MAAM,MAAM;AAAA,IACZ,UAAU,MAAM;AAAA,IAChB,MAAM,MAAM;AAAA,IACZ,QAAQ,MAAM;AAAA,EAAA;AAGhB,SAAO,OAAO,UAAU;AACtB,QAAI;AACJ,QAAI;AACF,YAAM,MAAM,MAAM,KAAK;AAAA,IACzB,SAAS,KAAK;AAGZ,YAAM,UAAU,eAAe,gBAAgB,IAAI,SAAS;AAC5D,UAAI,CAAC,SAAS;AACZ,eAAO;AAAA,UACL,QAAQ;AAAA,UACR;AAAA,UACA,SAAS,eAAe,QAAQ,IAAI,UAAU,OAAO,GAAG;AAAA,UACxD,OAAO;AAAA,UACP,SAAS,SAAS,KAAK;AAAA,QAAA,CACxB;AAAA,MACH;AACA,YAAM;AAAA,IACR;AAMA,QAAI,aAAa,CAAC,UAAU,GAAG,GAAG;AAChC,YAAM,UAAU,eAAe,GAAG,KAAK;AACvC,aAAO;AAAA,QACL,QAAQ;AAAA,QACR;AAAA,QACA;AAAA,QACA;AAAA,QACA,SAAS,SAAS,KAAK;AAAA,MAAA,CACxB;AACD,YAAM,IAAI,aAAa,YAAY,SAAS,GAAG;AAAA,IACjD;AAEA,QAAI;AACF,YAAM,UAAU,YAAY,KAAK,IAAI;AACrC,YAAM,aAAa,UAAU,SAAY,aAAa,KAAK,KAAK,IAAI,QAAQ;AAE5E,YAAM,OAAO,SACT,QAAQ,IAAI,CAAC,MAAM,UAAU,OAAO,MAAM,KAAK,CAAC,IAC/C;AAEL,aAAO,EAAE,MAAM,OAAO,WAAA;AAAA,IACxB,SAAS,KAAK;AAGZ,aAAO;AAAA,QACL,QAAQ;AAAA,QACR;AAAA,QACA,SAAS,eAAe,QAAQ,IAAI,UAAU,OAAO,GAAG;AAAA,QACxD;AAAA,QACA,OAAO;AAAA,QACP,SAAS,SAAS,KAAK;AAAA,MAAA,CACxB;AACD,YAAM;AAAA,IACR;AAAA,EACF;AACF;"}
|
package/dist/error.d.ts
ADDED
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* 数据层错误。
|
|
3
|
+
*
|
|
4
|
+
* 为什么要有专门的错误类型而不是 `new Error()`:
|
|
5
|
+
* · 调用方需要区分「业务失败」「字段路径写错」「网络失败」
|
|
6
|
+
* · 前两类是**开发期错误**(该在测试时发现),第三类是运行时错误
|
|
7
|
+
* · 错误信息里要带实际响应片段,否则排查要重新抓包
|
|
8
|
+
*/
|
|
9
|
+
export declare class FbkDataError extends Error {
|
|
10
|
+
/** 错误类别:业务码失败 / 路径解析失败 */
|
|
11
|
+
readonly kind: 'business' | 'path';
|
|
12
|
+
/** 后端原始响应(截断后),用于排查 */
|
|
13
|
+
readonly raw: unknown;
|
|
14
|
+
constructor(kind: 'business' | 'path', message: string, raw?: unknown);
|
|
15
|
+
}
|
|
16
|
+
/**
|
|
17
|
+
* 把响应截断成可读片段。
|
|
18
|
+
*
|
|
19
|
+
* 为什么要截断:某些后端失败时会返回整页 HTML(网关错误页),
|
|
20
|
+
* 直接把 10KB HTML 塞进错误信息会让控制台难以阅读。
|
|
21
|
+
*/
|
|
22
|
+
export declare function previewRaw(raw: unknown, limit?: number): string;
|
package/dist/error.mjs
ADDED
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
class FbkDataError extends Error {
|
|
2
|
+
/** 错误类别:业务码失败 / 路径解析失败 */
|
|
3
|
+
kind;
|
|
4
|
+
/** 后端原始响应(截断后),用于排查 */
|
|
5
|
+
raw;
|
|
6
|
+
constructor(kind, message, raw) {
|
|
7
|
+
super(message);
|
|
8
|
+
this.name = "FbkDataError";
|
|
9
|
+
this.kind = kind;
|
|
10
|
+
this.raw = raw;
|
|
11
|
+
}
|
|
12
|
+
}
|
|
13
|
+
function previewRaw(raw, limit = 500) {
|
|
14
|
+
let text;
|
|
15
|
+
try {
|
|
16
|
+
text = typeof raw === "string" ? raw : JSON.stringify(raw);
|
|
17
|
+
} catch {
|
|
18
|
+
text = String(raw);
|
|
19
|
+
}
|
|
20
|
+
if (text === void 0) return "undefined";
|
|
21
|
+
return text.length > limit ? `${text.slice(0, limit)}…(共 ${text.length} 字符)` : text;
|
|
22
|
+
}
|
|
23
|
+
export {
|
|
24
|
+
FbkDataError,
|
|
25
|
+
previewRaw
|
|
26
|
+
};
|
|
27
|
+
//# sourceMappingURL=error.mjs.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"error.mjs","sources":["../src/error.ts"],"sourcesContent":["/**\n * 数据层错误。\n *\n * 为什么要有专门的错误类型而不是 `new Error()`:\n * · 调用方需要区分「业务失败」「字段路径写错」「网络失败」\n * · 前两类是**开发期错误**(该在测试时发现),第三类是运行时错误\n * · 错误信息里要带实际响应片段,否则排查要重新抓包\n */\nexport class FbkDataError extends Error {\n /** 错误类别:业务码失败 / 路径解析失败 */\n readonly kind: 'business' | 'path'\n\n /** 后端原始响应(截断后),用于排查 */\n readonly raw: unknown\n\n constructor(kind: 'business' | 'path', message: string, raw?: unknown) {\n super(message)\n this.name = 'FbkDataError'\n this.kind = kind\n this.raw = raw\n }\n}\n\n/**\n * 把响应截断成可读片段。\n *\n * 为什么要截断:某些后端失败时会返回整页 HTML(网关错误页),\n * 直接把 10KB HTML 塞进错误信息会让控制台难以阅读。\n */\nexport function previewRaw(raw: unknown, limit = 500): string {\n let text: string\n try {\n text = typeof raw === 'string' ? raw : JSON.stringify(raw)\n } catch {\n // 循环引用等无法序列化的情况\n text = String(raw)\n }\n if (text === undefined) return 'undefined'\n return text.length > limit ? `${text.slice(0, limit)}…(共 ${text.length} 字符)` : text\n}\n"],"names":[],"mappings":"AAQO,MAAM,qBAAqB,MAAM;AAAA;AAAA,EAE7B;AAAA;AAAA,EAGA;AAAA,EAET,YAAY,MAA2B,SAAiB,KAAe;AACrE,UAAM,OAAO;AACb,SAAK,OAAO;AACZ,SAAK,OAAO;AACZ,SAAK,MAAM;AAAA,EACb;AACF;AAQO,SAAS,WAAW,KAAc,QAAQ,KAAa;AAC5D,MAAI;AACJ,MAAI;AACF,WAAO,OAAO,QAAQ,WAAW,MAAM,KAAK,UAAU,GAAG;AAAA,EAC3D,QAAQ;AAEN,WAAO,OAAO,GAAG;AAAA,EACnB;AACA,MAAI,SAAS,OAAW,QAAO;AAC/B,SAAO,KAAK,SAAS,QAAQ,GAAG,KAAK,MAAM,GAAG,KAAK,CAAC,OAAO,KAAK,MAAM,SAAS;AACjF;"}
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* 数据层契约。与后端规范、UI 库都无关。
|
|
3
|
+
*/
|
|
4
|
+
export { createPageRequest } from './create.js';
|
|
5
|
+
export { defineBackend } from './backend.js';
|
|
6
|
+
export { FbkDataError, previewRaw } from './error.js';
|
|
7
|
+
export { extractRows, extractTotal, getByPath } from './path.js';
|
|
8
|
+
export { assertServerScope } from './scope.js';
|
|
9
|
+
export type { Backend, BackendConfig, CreatePageRequestConfig, DataScope, Page, PageFetcher, PageQuery, PageSort, PathSpec, } from './types.js';
|
package/dist/index.mjs
ADDED
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
import { createPageRequest } from "./create.mjs";
|
|
2
|
+
import { defineBackend } from "./backend.mjs";
|
|
3
|
+
import { FbkDataError, previewRaw } from "./error.mjs";
|
|
4
|
+
import { extractRows, extractTotal, getByPath } from "./path.mjs";
|
|
5
|
+
import { assertServerScope } from "./scope.mjs";
|
|
6
|
+
export {
|
|
7
|
+
FbkDataError,
|
|
8
|
+
assertServerScope,
|
|
9
|
+
createPageRequest,
|
|
10
|
+
defineBackend,
|
|
11
|
+
extractRows,
|
|
12
|
+
extractTotal,
|
|
13
|
+
getByPath,
|
|
14
|
+
previewRaw
|
|
15
|
+
};
|
|
16
|
+
//# sourceMappingURL=index.mjs.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.mjs","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;"}
|
package/dist/path.d.ts
ADDED
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* 点号路径取值。
|
|
3
|
+
*
|
|
4
|
+
* 为什么需要它:真实后端的列表位置五花八门 ——
|
|
5
|
+
* `rows`(ruoyi)、`data.records`(很多 Spring 项目)、
|
|
6
|
+
* `data.list`、`result.items`……
|
|
7
|
+
*
|
|
8
|
+
* 业务方只需写一个字符串,不用写提取函数。
|
|
9
|
+
*
|
|
10
|
+
* **支持数组下标**:`data.list.0.items` 这类结构真实存在
|
|
11
|
+
* (某些接口把列表包在数组里)。
|
|
12
|
+
*/
|
|
13
|
+
export declare function getByPath(raw: unknown, path: string): unknown;
|
|
14
|
+
/**
|
|
15
|
+
* 从响应里取列表。
|
|
16
|
+
*
|
|
17
|
+
* 路径解析失败时**抛错而不是返回空数组** ——
|
|
18
|
+
* 返回空数组会让用户看到「暂无数据」,而真实原因是字段名写错。
|
|
19
|
+
*/
|
|
20
|
+
export declare function extractRows<TRaw>(raw: TRaw, spec: string | ((raw: TRaw) => unknown)): unknown[];
|
|
21
|
+
/**
|
|
22
|
+
* 从响应里取总数。失败时抛错。
|
|
23
|
+
*
|
|
24
|
+
* **null / '' / undefined 必须抛错,不能当成 0。**
|
|
25
|
+
*
|
|
26
|
+
* `Number(null) === 0`、`Number('') === 0` —— 这是挖过的坑:
|
|
27
|
+
* 后端返回 `total: null`(「暂无数据」或字段未初始化时很常见),
|
|
28
|
+
* 契约层静默变成 total=0,分页器显示「共 0 条」,
|
|
29
|
+
* 而实际可能有数据。用户看到的是错误信息,且没有任何报错。
|
|
30
|
+
*
|
|
31
|
+
* 宁可抛错让人发现,也不要静默显示错的分页。
|
|
32
|
+
*/
|
|
33
|
+
export declare function extractTotal<TRaw>(raw: TRaw, spec: string | ((raw: TRaw) => unknown)): number;
|
package/dist/path.mjs
ADDED
|
@@ -0,0 +1,74 @@
|
|
|
1
|
+
import { FbkDataError, previewRaw } from "./error.mjs";
|
|
2
|
+
function getByPath(raw, path) {
|
|
3
|
+
if (!path) return raw;
|
|
4
|
+
const segments = path.split(".");
|
|
5
|
+
let current = raw;
|
|
6
|
+
for (const segment of segments) {
|
|
7
|
+
if (current === null || current === void 0) {
|
|
8
|
+
throw new FbkDataError(
|
|
9
|
+
"path",
|
|
10
|
+
`[fbk/data] 路径 "${path}" 解析失败:在第 "${segment}" 段时父级为 ${current}。实际响应:${previewRaw(raw)}`,
|
|
11
|
+
raw
|
|
12
|
+
);
|
|
13
|
+
}
|
|
14
|
+
if (typeof current !== "object") {
|
|
15
|
+
throw new FbkDataError(
|
|
16
|
+
"path",
|
|
17
|
+
`[fbk/data] 路径 "${path}" 解析失败:第 "${segment}" 段无法从 ${typeof current} 上取属性。实际响应:${previewRaw(raw)}`,
|
|
18
|
+
raw
|
|
19
|
+
);
|
|
20
|
+
}
|
|
21
|
+
if (Array.isArray(current) && /^\d+$/.test(segment)) {
|
|
22
|
+
current = current[Number(segment)];
|
|
23
|
+
} else {
|
|
24
|
+
current = current[segment];
|
|
25
|
+
}
|
|
26
|
+
}
|
|
27
|
+
if (current === void 0) {
|
|
28
|
+
throw new FbkDataError(
|
|
29
|
+
"path",
|
|
30
|
+
`[fbk/data] 路径 "${path}" 解析结果为 undefined。多半是字段名写错了 —— 注意:静默返回空列表会让这类错误极难排查。实际响应:${previewRaw(raw)}`,
|
|
31
|
+
raw
|
|
32
|
+
);
|
|
33
|
+
}
|
|
34
|
+
return current;
|
|
35
|
+
}
|
|
36
|
+
function extractRows(raw, spec) {
|
|
37
|
+
const value = typeof spec === "function" ? spec(raw) : getByPath(raw, spec);
|
|
38
|
+
if (!Array.isArray(value)) {
|
|
39
|
+
throw new FbkDataError(
|
|
40
|
+
"path",
|
|
41
|
+
`[fbk/data] 列表位置不是数组(实际是 ${typeof value})。实际响应:${previewRaw(raw)}`,
|
|
42
|
+
raw
|
|
43
|
+
);
|
|
44
|
+
}
|
|
45
|
+
return value;
|
|
46
|
+
}
|
|
47
|
+
function extractTotal(raw, spec) {
|
|
48
|
+
const value = typeof spec === "function" ? spec(raw) : getByPath(raw, spec);
|
|
49
|
+
if (value === null || value === void 0 || value === "") {
|
|
50
|
+
throw new FbkDataError(
|
|
51
|
+
"path",
|
|
52
|
+
`[fbk/data] 总数位置是 ${value === "" ? "空字符串" : String(value)},不是有效数字。
|
|
53
|
+
Number(null) === 0,如果静默转换,分页器会显示「共 0 条」但实际可能有数据。
|
|
54
|
+
如果后端确实没有总数,请改用 total: (raw) => rows.length 或直接不传 total。
|
|
55
|
+
实际响应:${previewRaw(raw)}`,
|
|
56
|
+
raw
|
|
57
|
+
);
|
|
58
|
+
}
|
|
59
|
+
const num = Number(value);
|
|
60
|
+
if (!Number.isFinite(num)) {
|
|
61
|
+
throw new FbkDataError(
|
|
62
|
+
"path",
|
|
63
|
+
`[fbk/data] 总数位置不是有效数字(实际是 ${previewRaw(value)})。实际响应:${previewRaw(raw)}`,
|
|
64
|
+
raw
|
|
65
|
+
);
|
|
66
|
+
}
|
|
67
|
+
return num;
|
|
68
|
+
}
|
|
69
|
+
export {
|
|
70
|
+
extractRows,
|
|
71
|
+
extractTotal,
|
|
72
|
+
getByPath
|
|
73
|
+
};
|
|
74
|
+
//# sourceMappingURL=path.mjs.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"path.mjs","sources":["../src/path.ts"],"sourcesContent":["import { FbkDataError, previewRaw } from './error'\n\n/**\n * 点号路径取值。\n *\n * 为什么需要它:真实后端的列表位置五花八门 ——\n * `rows`(ruoyi)、`data.records`(很多 Spring 项目)、\n * `data.list`、`result.items`……\n *\n * 业务方只需写一个字符串,不用写提取函数。\n *\n * **支持数组下标**:`data.list.0.items` 这类结构真实存在\n * (某些接口把列表包在数组里)。\n */\nexport function getByPath(raw: unknown, path: string): unknown {\n if (!path) return raw\n\n const segments = path.split('.')\n let current: unknown = raw\n\n for (const segment of segments) {\n if (current === null || current === undefined) {\n throw new FbkDataError(\n 'path',\n `[fbk/data] 路径 \"${path}\" 解析失败:在第 \"${segment}\" 段时父级为 ${current}。` +\n `实际响应:${previewRaw(raw)}`,\n raw,\n )\n }\n\n if (typeof current !== 'object') {\n throw new FbkDataError(\n 'path',\n `[fbk/data] 路径 \"${path}\" 解析失败:第 \"${segment}\" 段无法从 ${typeof current} 上取属性。` +\n `实际响应:${previewRaw(raw)}`,\n raw,\n )\n }\n\n // 数组下标:'0' 这类纯数字段\n if (Array.isArray(current) && /^\\d+$/.test(segment)) {\n current = current[Number(segment)]\n } else {\n current = (current as Record<string, unknown>)[segment]\n }\n }\n\n if (current === undefined) {\n throw new FbkDataError(\n 'path',\n `[fbk/data] 路径 \"${path}\" 解析结果为 undefined。` +\n `多半是字段名写错了 —— 注意:静默返回空列表会让这类错误极难排查。` +\n `实际响应:${previewRaw(raw)}`,\n raw,\n )\n }\n\n return current\n}\n\n/**\n * 从响应里取列表。\n *\n * 路径解析失败时**抛错而不是返回空数组** ——\n * 返回空数组会让用户看到「暂无数据」,而真实原因是字段名写错。\n */\nexport function extractRows<TRaw>(raw: TRaw, spec: string | ((raw: TRaw) => unknown)): unknown[] {\n const value = typeof spec === 'function' ? spec(raw) : getByPath(raw, spec)\n\n if (!Array.isArray(value)) {\n throw new FbkDataError(\n 'path',\n `[fbk/data] 列表位置不是数组(实际是 ${typeof value})。实际响应:${previewRaw(raw)}`,\n raw,\n )\n }\n return value\n}\n\n/**\n * 从响应里取总数。失败时抛错。\n *\n * **null / '' / undefined 必须抛错,不能当成 0。**\n *\n * `Number(null) === 0`、`Number('') === 0` —— 这是挖过的坑:\n * 后端返回 `total: null`(「暂无数据」或字段未初始化时很常见),\n * 契约层静默变成 total=0,分页器显示「共 0 条」,\n * 而实际可能有数据。用户看到的是错误信息,且没有任何报错。\n *\n * 宁可抛错让人发现,也不要静默显示错的分页。\n */\nexport function extractTotal<TRaw>(\n raw: TRaw,\n spec: string | ((raw: TRaw) => unknown),\n): number {\n const value = typeof spec === 'function' ? spec(raw) : getByPath(raw, spec)\n\n if (value === null || value === undefined || value === '') {\n throw new FbkDataError(\n 'path',\n `[fbk/data] 总数位置是 ${value === '' ? '空字符串' : String(value)},不是有效数字。` +\n `\\n Number(null) === 0,如果静默转换,分页器会显示「共 0 条」但实际可能有数据。` +\n `\\n 如果后端确实没有总数,请改用 total: (raw) => rows.length 或直接不传 total。` +\n `\\n 实际响应:${previewRaw(raw)}`,\n raw,\n )\n }\n\n const num = Number(value)\n\n if (!Number.isFinite(num)) {\n throw new FbkDataError(\n 'path',\n `[fbk/data] 总数位置不是有效数字(实际是 ${previewRaw(value)})。` +\n `实际响应:${previewRaw(raw)}`,\n raw,\n )\n }\n return num\n}\n"],"names":[],"mappings":";AAcO,SAAS,UAAU,KAAc,MAAuB;AAC7D,MAAI,CAAC,KAAM,QAAO;AAElB,QAAM,WAAW,KAAK,MAAM,GAAG;AAC/B,MAAI,UAAmB;AAEvB,aAAW,WAAW,UAAU;AAC9B,QAAI,YAAY,QAAQ,YAAY,QAAW;AAC7C,YAAM,IAAI;AAAA,QACR;AAAA,QACA,kBAAkB,IAAI,cAAc,OAAO,WAAW,OAAO,SACnD,WAAW,GAAG,CAAC;AAAA,QACzB;AAAA,MAAA;AAAA,IAEJ;AAEA,QAAI,OAAO,YAAY,UAAU;AAC/B,YAAM,IAAI;AAAA,QACR;AAAA,QACA,kBAAkB,IAAI,aAAa,OAAO,UAAU,OAAO,OAAO,cACxD,WAAW,GAAG,CAAC;AAAA,QACzB;AAAA,MAAA;AAAA,IAEJ;AAGA,QAAI,MAAM,QAAQ,OAAO,KAAK,QAAQ,KAAK,OAAO,GAAG;AACnD,gBAAU,QAAQ,OAAO,OAAO,CAAC;AAAA,IACnC,OAAO;AACL,gBAAW,QAAoC,OAAO;AAAA,IACxD;AAAA,EACF;AAEA,MAAI,YAAY,QAAW;AACzB,UAAM,IAAI;AAAA,MACR;AAAA,MACA,kBAAkB,IAAI,4DAEZ,WAAW,GAAG,CAAC;AAAA,MACzB;AAAA,IAAA;AAAA,EAEJ;AAEA,SAAO;AACT;AAQO,SAAS,YAAkB,KAAW,MAAoD;AAC/F,QAAM,QAAQ,OAAO,SAAS,aAAa,KAAK,GAAG,IAAI,UAAU,KAAK,IAAI;AAE1E,MAAI,CAAC,MAAM,QAAQ,KAAK,GAAG;AACzB,UAAM,IAAI;AAAA,MACR;AAAA,MACA,2BAA2B,OAAO,KAAK,UAAU,WAAW,GAAG,CAAC;AAAA,MAChE;AAAA,IAAA;AAAA,EAEJ;AACA,SAAO;AACT;AAcO,SAAS,aACd,KACA,MACQ;AACR,QAAM,QAAQ,OAAO,SAAS,aAAa,KAAK,GAAG,IAAI,UAAU,KAAK,IAAI;AAE1E,MAAI,UAAU,QAAQ,UAAU,UAAa,UAAU,IAAI;AACzD,UAAM,IAAI;AAAA,MACR;AAAA,MACA,oBAAoB,UAAU,KAAK,SAAS,OAAO,KAAK,CAAC;AAAA;AAAA;AAAA,SAG3C,WAAW,GAAG,CAAC;AAAA,MAC7B;AAAA,IAAA;AAAA,EAEJ;AAEA,QAAM,MAAM,OAAO,KAAK;AAExB,MAAI,CAAC,OAAO,SAAS,GAAG,GAAG;AACzB,UAAM,IAAI;AAAA,MACR;AAAA,MACA,6BAA6B,WAAW,KAAK,CAAC,UACpC,WAAW,GAAG,CAAC;AAAA,MACzB;AAAA,IAAA;AAAA,EAEJ;AACA,SAAO;AACT;"}
|
package/dist/scope.d.ts
ADDED
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* 数据级权限提醒。
|
|
3
|
+
*
|
|
4
|
+
* **这不是校验 —— 前端无法真正校验权限。**
|
|
5
|
+
* 若接口返回了 1000 条,前端隐藏 900 条,那 1000 条依然在
|
|
6
|
+
* 浏览器 Network 面板里。任何有浏览器的人都能看到。
|
|
7
|
+
*
|
|
8
|
+
* 它的价值在于:把「前端隐藏不构成权限」这件事,
|
|
9
|
+
* 出现在写代码的那一刻,而不是等安全审计时被指出来。
|
|
10
|
+
*
|
|
11
|
+
* 仅开发环境提醒。用 NODE_ENV 而不是 import.meta.env:
|
|
12
|
+
* 后者依赖 vite 类型,会让这个纯逻辑包绑定构建工具。
|
|
13
|
+
*/
|
|
14
|
+
export declare function assertServerScope(feature: string): void;
|
package/dist/scope.mjs
ADDED
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
import { warnOnce } from "@fbkworks/shared";
|
|
2
|
+
function assertServerScope(feature) {
|
|
3
|
+
if (typeof process !== "undefined" && process.env?.NODE_ENV === "production") return;
|
|
4
|
+
warnOnce(
|
|
5
|
+
`data-scope-${feature}`,
|
|
6
|
+
`[fbk/data] "${feature}" 的数据级权限必须由服务端过滤。
|
|
7
|
+
前端隐藏不构成权限 —— 列表接口已返回全部数据,
|
|
8
|
+
任何用户都能在浏览器 Network 面板看到完整内容。
|
|
9
|
+
如果你确认服务端已按权限过滤,可以忽略这条提醒,
|
|
10
|
+
或改用 createPageRequest({ scope: "server-filtered" }) 显式声明。`
|
|
11
|
+
);
|
|
12
|
+
}
|
|
13
|
+
export {
|
|
14
|
+
assertServerScope
|
|
15
|
+
};
|
|
16
|
+
//# sourceMappingURL=scope.mjs.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"scope.mjs","sources":["../src/scope.ts"],"sourcesContent":["import { warnOnce } from '@fbkworks/shared'\n\n/**\n * 数据级权限提醒。\n *\n * **这不是校验 —— 前端无法真正校验权限。**\n * 若接口返回了 1000 条,前端隐藏 900 条,那 1000 条依然在\n * 浏览器 Network 面板里。任何有浏览器的人都能看到。\n *\n * 它的价值在于:把「前端隐藏不构成权限」这件事,\n * 出现在写代码的那一刻,而不是等安全审计时被指出来。\n *\n * 仅开发环境提醒。用 NODE_ENV 而不是 import.meta.env:\n * 后者依赖 vite 类型,会让这个纯逻辑包绑定构建工具。\n */\nexport function assertServerScope(feature: string): void {\n // 生产环境直接返回,零开销\n if (typeof process !== 'undefined' && process.env?.NODE_ENV === 'production') return\n\n warnOnce(\n `data-scope-${feature}`,\n `[fbk/data] \"${feature}\" 的数据级权限必须由服务端过滤。\\n` +\n ' 前端隐藏不构成权限 —— 列表接口已返回全部数据,\\n' +\n ' 任何用户都能在浏览器 Network 面板看到完整内容。\\n' +\n ' 如果你确认服务端已按权限过滤,可以忽略这条提醒,\\n' +\n ' 或改用 createPageRequest({ scope: \"server-filtered\" }) 显式声明。',\n )\n}\n"],"names":[],"mappings":";AAeO,SAAS,kBAAkB,SAAuB;AAEvD,MAAI,OAAO,YAAY,eAAe,QAAQ,KAAK,aAAa,aAAc;AAE9E;AAAA,IACE,cAAc,OAAO;AAAA,IACrB,eAAe,OAAO;AAAA;AAAA;AAAA;AAAA;AAAA,EAAA;AAM1B;"}
|
package/dist/types.d.ts
ADDED
|
@@ -0,0 +1,184 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* 数据层契约类型。
|
|
3
|
+
*
|
|
4
|
+
* **这里是分页契约的唯一定义处。** `@fbkworks/components` 的
|
|
5
|
+
* `TableRequestParams` / `TableResponse` / `TableRequest` 都是
|
|
6
|
+
* 本文件类型的别名 —— 改这里就会一起变,不存在两处漂移。
|
|
7
|
+
*
|
|
8
|
+
* 设计原则(见 docs/design/2026-10-25-fbk-data-contract.md):
|
|
9
|
+
* · 与**后端规范无关** —— 不认识 ruoyi、Spring、GraphQL
|
|
10
|
+
* · 与 **UI 库无关** —— 不依赖 @fbkworks/adapter-core
|
|
11
|
+
* · 传输层注入 —— 不内置 axios / fetch
|
|
12
|
+
*/
|
|
13
|
+
/**
|
|
14
|
+
* 排序状态。
|
|
15
|
+
*
|
|
16
|
+
* 与 `@fbkworks/adapter-core` 的 `SortState` 结构一致,但这里独立声明:
|
|
17
|
+
* 数据层不该为了一个两字段的结构去依赖 UI 适配层。
|
|
18
|
+
* 一致性由 `packages/data/tests/contract.spec.ts` 的类型断言保证。
|
|
19
|
+
*/
|
|
20
|
+
export interface PageSort {
|
|
21
|
+
field: string;
|
|
22
|
+
order: 'asc' | 'desc' | null;
|
|
23
|
+
}
|
|
24
|
+
/**
|
|
25
|
+
* 一页数据。
|
|
26
|
+
*
|
|
27
|
+
* `total` 必填 —— `createPageRequest` 一定会算出总数
|
|
28
|
+
* (没有 total 字段时取 rows.length)。业务方手写 fetcher 时
|
|
29
|
+
* 若拿不到总数,用 `TableResponse`(它的 total 是可选的)。
|
|
30
|
+
*/
|
|
31
|
+
export interface Page<T> {
|
|
32
|
+
list: T[];
|
|
33
|
+
total: number;
|
|
34
|
+
/** 无限滚动场景:false 表示没有更多了 */
|
|
35
|
+
hasMore?: boolean;
|
|
36
|
+
}
|
|
37
|
+
/**
|
|
38
|
+
* 分页查询参数。
|
|
39
|
+
*
|
|
40
|
+
* `signal` 是必须的 —— 竞态处理(快速翻页时丢弃旧响应)依赖它。
|
|
41
|
+
*/
|
|
42
|
+
export interface PageQuery {
|
|
43
|
+
page: number;
|
|
44
|
+
pageSize: number;
|
|
45
|
+
sort: PageSort | null;
|
|
46
|
+
params: Record<string, any>;
|
|
47
|
+
signal: AbortSignal;
|
|
48
|
+
}
|
|
49
|
+
/** 分页取数函数。业务方实现这个即可接入 ProTable / CrudPage */
|
|
50
|
+
export type PageFetcher<T> = (query: PageQuery) => Promise<Page<T>>;
|
|
51
|
+
/**
|
|
52
|
+
* 数据级权限声明。
|
|
53
|
+
*
|
|
54
|
+
* `server-filtered`:数据已由服务端按当前用户权限过滤(正确做法)
|
|
55
|
+
* `client-filtered`:前端拿到全量再隐藏(**不构成权限**,dev 环境会 warn)
|
|
56
|
+
*/
|
|
57
|
+
export type DataScope = 'server-filtered' | 'client-filtered';
|
|
58
|
+
/** 路径:点号字符串,或自定义提取函数 */
|
|
59
|
+
export type PathSpec<TRaw> = string | ((raw: TRaw) => unknown);
|
|
60
|
+
export interface CreatePageRequestConfig<TRaw, T> {
|
|
61
|
+
/**
|
|
62
|
+
* 实际发请求。由调用方注入。
|
|
63
|
+
*
|
|
64
|
+
* 库刻意不内置 HTTP 客户端 —— 传输层是应用决策(axios / fetch / 自研),
|
|
65
|
+
* 库无权锁定。这条由 eslint 的第一类禁止依赖约束保证。
|
|
66
|
+
*/
|
|
67
|
+
fetch: (query: PageQuery) => Promise<TRaw>;
|
|
68
|
+
/**
|
|
69
|
+
* 列表在响应里的位置。
|
|
70
|
+
*
|
|
71
|
+
* 字符串用点号路径(支持数组下标),或直接给函数。
|
|
72
|
+
* 例:`'rows'`、`'data.records'`、`(res) => res.data.items`
|
|
73
|
+
*/
|
|
74
|
+
rows: PathSpec<TRaw>;
|
|
75
|
+
/** 总数位置。不传时用 rows.length(适合一次性返回全部的场景) */
|
|
76
|
+
total?: PathSpec<TRaw>;
|
|
77
|
+
/** 行映射:把后端原始行转成业务模型 */
|
|
78
|
+
mapRow?: (raw: unknown, index: number) => T;
|
|
79
|
+
/**
|
|
80
|
+
* 业务码判定。不传视为 HTTP 层已保证成功。
|
|
81
|
+
*
|
|
82
|
+
* 有业务码的后端(如 ruoyi 的 `code === 200`)必须传,
|
|
83
|
+
* 否则失败响应会被当成空列表。
|
|
84
|
+
*/
|
|
85
|
+
isSuccess?: (raw: TRaw) => boolean;
|
|
86
|
+
/** 失败时的错误信息提取 */
|
|
87
|
+
errorMessage?: (raw: TRaw) => string;
|
|
88
|
+
/**
|
|
89
|
+
* 数据级权限声明。
|
|
90
|
+
*
|
|
91
|
+
* 传 `'client-filtered'` 会在 dev 环境 warn —— 前端隐藏不构成权限。
|
|
92
|
+
*/
|
|
93
|
+
scope?: DataScope;
|
|
94
|
+
/**
|
|
95
|
+
* 业务标识,用于在错误上报里区分是哪个接口。
|
|
96
|
+
* 通常传接口名,如 'order.list'。
|
|
97
|
+
*/
|
|
98
|
+
feature?: string;
|
|
99
|
+
/**
|
|
100
|
+
* 错误钩子。请求失败、业务码失败、路径解析失败都会走它。
|
|
101
|
+
*
|
|
102
|
+
* 为什么是**注入回调**而不是读全局 reporter:
|
|
103
|
+
* 这个包是纯逻辑层,不依赖 Vue 也不依赖 adapter-core。
|
|
104
|
+
* 业务方在应用入口把它接到统一的 onError 即可:
|
|
105
|
+
* ```ts
|
|
106
|
+
* createPageRequest({
|
|
107
|
+
* fetch, rows: 'rows',
|
|
108
|
+
* onError: (event) => reporter.error(event),
|
|
109
|
+
* })
|
|
110
|
+
* ```
|
|
111
|
+
*/
|
|
112
|
+
onError?: (event: PageRequestErrorEvent) => void;
|
|
113
|
+
}
|
|
114
|
+
/** 数据层错误事件。与 adapter-core 的 FbkErrorEvent 形状对齐,但不依赖它 */
|
|
115
|
+
export interface PageRequestErrorEvent {
|
|
116
|
+
/** 固定为 'request',与 FbkErrorEvent.source 对齐 */
|
|
117
|
+
source: 'request';
|
|
118
|
+
/** 业务标识:通常是接口名,由 feature 选项提供 */
|
|
119
|
+
feature?: string;
|
|
120
|
+
message: string;
|
|
121
|
+
/** 原始响应(截断后)。网络层错误时为 undefined */
|
|
122
|
+
raw?: unknown;
|
|
123
|
+
/** 原始异常(fetch 抛错时) */
|
|
124
|
+
cause?: unknown;
|
|
125
|
+
/** 本次请求的参数快照(用于复现) */
|
|
126
|
+
context?: Record<string, unknown>;
|
|
127
|
+
}
|
|
128
|
+
/**
|
|
129
|
+
* 后端惯例配置。
|
|
130
|
+
*
|
|
131
|
+
* 描述「这个后端长什么样」—— 一次,全项目复用。
|
|
132
|
+
* 接口特有的信息(URL、feature、mapRow)不在这里。
|
|
133
|
+
*/
|
|
134
|
+
export interface BackendConfig<TRaw = any> {
|
|
135
|
+
/**
|
|
136
|
+
* 传输层。签名固定,A 形态依赖它。
|
|
137
|
+
*
|
|
138
|
+
* `params` 已经过 `mapParams` 转换,直接透传给 HTTP 客户端即可。
|
|
139
|
+
*/
|
|
140
|
+
request: (url: string, params: Record<string, any>, signal: AbortSignal) => Promise<TRaw>;
|
|
141
|
+
/** 列表在响应里的位置 */
|
|
142
|
+
rows: PathSpec<TRaw>;
|
|
143
|
+
/** 总数位置。不传时用 rows.length */
|
|
144
|
+
total?: PathSpec<TRaw>;
|
|
145
|
+
/** 业务码判定 */
|
|
146
|
+
isSuccess?: (raw: TRaw) => boolean;
|
|
147
|
+
/** 失败时的错误信息提取 */
|
|
148
|
+
errorMessage?: (raw: TRaw) => string;
|
|
149
|
+
/** 数据级权限声明 */
|
|
150
|
+
scope?: DataScope;
|
|
151
|
+
/** 错误上报钩子 */
|
|
152
|
+
onError?: (event: PageRequestErrorEvent) => void;
|
|
153
|
+
/**
|
|
154
|
+
* `PageQuery` → 后端参数名。
|
|
155
|
+
*
|
|
156
|
+
* 不传时直接用 `{ page, pageSize, ...params }`。
|
|
157
|
+
* 后端用 `pageNum` 的项目需要显式传:
|
|
158
|
+
* ```ts
|
|
159
|
+
* mapParams: ({ page, pageSize, params }) => ({ pageNum: page, pageSize, ...params })
|
|
160
|
+
* ```
|
|
161
|
+
*/
|
|
162
|
+
mapParams?: (query: PageQuery) => Record<string, any>;
|
|
163
|
+
}
|
|
164
|
+
/** 接口级配置:覆盖后端惯例的任意字段(`fetch` 除外,由 defineBackend 生成) */
|
|
165
|
+
export type PageOptions<TRaw, T> = Partial<Omit<CreatePageRequestConfig<TRaw, T>, 'fetch'>>;
|
|
166
|
+
export interface Backend<TRaw = any> {
|
|
167
|
+
/**
|
|
168
|
+
* 创建一个分页取数函数。
|
|
169
|
+
*
|
|
170
|
+
* **A 形态**:传字符串路径,用后端惯例的 `request` 发请求
|
|
171
|
+
* ```ts
|
|
172
|
+
* api.page('/api/order/list', { feature: 'order.list' })
|
|
173
|
+
* ```
|
|
174
|
+
*
|
|
175
|
+
* **B 形态**:传 fetcher,逃生口(URL 动态拼接、特殊 header 等)
|
|
176
|
+
* ```ts
|
|
177
|
+
* api.page(({ page, pageSize, signal }) =>
|
|
178
|
+
* http.get(`/api/${tenant}/list`, { params: { pageNum: page, pageSize }, signal }))
|
|
179
|
+
* ```
|
|
180
|
+
*/
|
|
181
|
+
page<T = unknown>(pathOrFetcher: string | ((query: PageQuery) => Promise<TRaw>), options?: PageOptions<TRaw, T>): PageFetcher<T>;
|
|
182
|
+
/** 底层配置。便于测试与高级用法(例如在别处复用同一个 request) */
|
|
183
|
+
readonly config: BackendConfig<TRaw>;
|
|
184
|
+
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,50 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@fbkworks/data",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
3
|
+
"version": "0.2.0",
|
|
4
|
+
"type": "module",
|
|
5
|
+
"sideEffects": false,
|
|
6
|
+
"files": [
|
|
7
|
+
"dist",
|
|
8
|
+
"README.md",
|
|
9
|
+
"LICENSE"
|
|
10
|
+
],
|
|
11
|
+
"types": "./dist/index.d.ts",
|
|
12
|
+
"exports": {
|
|
13
|
+
".": {
|
|
14
|
+
"types": "./dist/index.d.ts",
|
|
15
|
+
"import": "./dist/index.mjs"
|
|
16
|
+
},
|
|
17
|
+
"./package.json": "./package.json"
|
|
18
|
+
},
|
|
19
|
+
"dependencies": {
|
|
20
|
+
"@fbkworks/shared": "^0.2.0"
|
|
21
|
+
},
|
|
22
|
+
"publishConfig": {
|
|
23
|
+
"access": "public"
|
|
24
|
+
},
|
|
25
|
+
"description": "Backend-agnostic data contracts (paging, response mapping, permission scope) for the FBK kit.",
|
|
26
|
+
"keywords": [
|
|
27
|
+
"vue",
|
|
28
|
+
"pagination",
|
|
29
|
+
"data-layer",
|
|
30
|
+
"contract",
|
|
31
|
+
"fbk"
|
|
32
|
+
],
|
|
33
|
+
"license": "MIT",
|
|
34
|
+
"author": "54356",
|
|
35
|
+
"homepage": "https://github.com/54356/frontend-business-kit#readme",
|
|
36
|
+
"repository": {
|
|
37
|
+
"type": "git",
|
|
38
|
+
"url": "git+https://github.com/54356/frontend-business-kit.git",
|
|
39
|
+
"directory": "packages/data"
|
|
40
|
+
},
|
|
41
|
+
"bugs": {
|
|
42
|
+
"url": "https://github.com/54356/frontend-business-kit/issues"
|
|
43
|
+
},
|
|
44
|
+
"engines": {
|
|
45
|
+
"node": ">=20.11.0"
|
|
46
|
+
},
|
|
47
|
+
"scripts": {
|
|
48
|
+
"build": "vite build"
|
|
49
|
+
}
|
|
6
50
|
}
|
package/README.md
DELETED