zentao-api 0.3.0 → 0.3.2

package/README.md

@@ -57,6 +57,14 @@ setGlobalOptions({ recPerPage: '50' });
 const result = await request('product/list', {});
 ```
 
+请求名支持三种写法：
+
+```ts
+await request('product');      // 默认调用 product/list
+await request('product/list'); // 显式调用模块动作
+await request('product/1');    // 详情快捷写法，等价于 product/get + id=1
+```
+
 单次调用的选项会覆盖全局选项：
 
 ```ts
@@ -93,11 +101,13 @@ const client = await ZentaoClient.fromProfile('admin@https://zentao.example.com'
 
 | 函数 | 说明 |
 |------|------|
-| `request(name, params?, options?)` | 按 `"module/action"` 格式调用已注册模块 |
+| `request(name, params?, options?)` | 按 `"module"`、`"module/action"` 或 `"module/<objectID>"` 调用已注册模块 |
 | `defineModules(modules, options?)` | 注册或扩展模块定义 |
 | `defineModuleActions(module, actions)` | 为已有模块追加或替换动作 |
+| `extendModuleAction(module, action, patch)` | 深度合并补丁，或用回调改写已有动作 |
 | `getModule(name)` | 获取模块定义 |
 | `getModuleAction(module, action)` | 获取指定动作定义 |
+| `getModuleNames()` | 获取所有已注册模块名 |
 | `setGlobalOptions(options)` | 设置全局默认选项 |
 | `getGlobalOptions()` | 获取当前全局选项 |
 
@@ -118,7 +128,7 @@ try {
 }
 ```
 
-> **注意**：服务端返回 `{ status: "fail" }` 时 SDK 不会抛出异常，按原始响应内容返回。仅 HTTP/网络/超时等传输层错误会抛出 `ZentaoError`。
+> **注意**：服务端返回 `{ status: "fail" }` 时 SDK 默认不会抛出异常，按原始响应内容返回。需要把业务失败转为异常时，可在单次请求或全局选项中启用 `throwOnFail`。HTTP/网络/超时等传输层错误始终会抛出 `ZentaoError`。
 
 ## 扩展模块
 
@@ -159,6 +169,32 @@ defineModuleActions('bug', {
 });
 ```
 
+### 微调已有动作
+
+只想改动作的个别字段（而不是整体替换）时，用 `extendModuleAction`。传入补丁对象会与原动作**深度合并**：普通对象递归合并，数组及其他值整体替换，`undefined` 的键会被忽略。
+
+```ts
+import { extendModuleAction } from 'zentao-api';
+
+// 改写 task/list 的 URL
+extendModuleAction('task', 'list', {
+  path: '/executions/{executionID}/tasks',
+  pathParams: { executionID: '执行ID' },
+});
+```
+
+需要基于现有定义做条件改写时，可传入回调。回调收到当前动作的深克隆，返回值作为**完整**动作定义直接取代原动作（不再合并）：
+
+```ts
+extendModuleAction('execution', 'create', (action) => {
+  const required = action.requestBody!.schema?.required;
+  if (Array.isArray(required) && !required.includes('products')) {
+    required.push('products');
+  }
+  return action;
+});
+```
+
 ### 合并与替换
 
 同名模块默认**合并**定义：同名动作会替换，未知动作会追加。如需**整体替换**模块，传入 `{ replace: true }`：