Przejdź do treści
Biblioteka skilli
Programowanie · Budowanie i kod

s04-06-api-client-wrapper

/s04-06-api-client-wrapper

Zamienia endpointy API na typowany zestaw funkcji dla frontendu i mini programu, czyli SDK z definicjami typów.

Licencja
MIT
Ostatnia zmiana repozytorium
01.11.2026

Ocena i bezpieczeństwo

96/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność21 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
1
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
0
Przestarzałość

Brak sygnałów. Repozytorium zmienione 01.11.2026, bez odwołań do wycofanych modeli i API.

Licencja

MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.

Co robi i kiedy

Zamienia endpointy API na typowany zestaw funkcji dla frontendu i mini programu, czyli SDK z definicjami typów.

Wyzwalacze z opisu

封装请求/生成接口 SDK/前后端对接

Argumenty

/s04-06-api-client-wrapper [openapi路径] [目标语言]
Oryginalny opis (EN)

把后端接口封装为前端/小程序可直接调用的类型化 SDK。当用户要求'封装请求/生成接口 SDK/前后端对接'时使用。产出 api 层源码与类型定义。

Jak działa

  1. 0. 契约卡(CONTRACT)
  2. 1. 调用方式
  3. 2. 前置条件(未满足即停手回报,不得带病执行)
  4. 3. 输入
  5. 4. 执行步骤
  6. 5. 输出契约(精确路径)
  7. 6. 治理汇报协议(★ 强制)
  8. 多人并行开发规则(本技能强制适用)
  9. 7. 必须真实执行的验证命令
  10. 8. 完成判据(DoD)
Sekcje z nagłówków SKILL.md, w oryginale · 210 linii, 652 słów
Podgląd SKILL.md
---
name: "s04-06-api-client-wrapper"
description: "把后端接口封装为前端/小程序可直接调用的类型化 SDK。当用户要求'封装请求/生成接口 SDK/前后端对接'时使用。产出 api 层源码与类型定义。"
allowed-tools: "Read, Write, Edit, Bash"
argument-hint: "[openapi路径] [目标语言]"
---

# 接口封装 `S04-06-api-client-wrapper`

> 分组:S04 开发编码 | 主责阶段:STAGE_4 | 负责角色:`developer`

**职责边界**:只做编码:脚手架/CRUD/页面/组件/接口封装/工具类/校验/单测/注释/lint/README。不改契约,不改基线。

## 0. 契约卡(CONTRACT)

| 契约项 | 值 |
|---|---|
| 技能ID | `S04-06-api-client-wrapper` |
| 分组 | S04 开发编码 |
| 主责阶段 | STAGE_4 |
| 负责角色 | `developer` |
| 产物根目录 | `src/` |
| 前置门禁 | `G1_input_ready`、`G2_channel_check`、`G3_oss_and_baseline`、`G4_design_review` |
| 允许写入 | `src/` 及本技能「输出契约」列出的路径 |
| 禁止触碰 | `state/**`、`baseline/**`(受 protect_state 钩子硬拦截) |
| 越权后果 | 不在 RTM/基线内的需求 = 超范围,须 `scope check` 后走变更单 |

> 契约卡随技能一起注入,**不依赖对话记忆**。若与对话中说法冲突,以本卡为准。

## 1. 调用方式

```bash
/commercial-multiagent-sdlc:s04-06-api-client-wrapper [openapi路径] [目标语言]
用 S04-06-api-client-wrapper 这个技能做接口封装
```

## 2. 前置条件(未满足即停手回报,不得带病执行)

- openapi.yaml 已产出

门禁硬校验(引擎执行,模型无法绕过):

```bash
python "${CLAUDE_PLUGIN_ROOT}/scripts/governance.py" gate check G1_input_ready
python "${CLAUDE_PLUGIN_ROOT}/scripts/governance.py" gate check G2_channel_check
python "${CLAUDE_PLUGIN_ROOT}/scripts/governance.py" gate check G3_oss_and_baseline
python "${CLAUDE_PLUGIN_ROOT}/scripts/governance.py" gate check G4_design_review
```

## 3. 输入

- artifacts/stage3-design/openapi.yaml

## 4. 执行步骤

1. 按 openapi 生成请求方法与出入参类型定义
2. 统一拦截:鉴权头、错误码映射、重试退避、取消请求
3. 超时与网络异常统一提示文案
4. 生成 mock 数据便于前端独立联调
5. 与后端契约做字段级比对,差异写进报告

**命名规范**:`按项目既有规范;模块目录 src/backend/<module>/{entity,dto,service,controller,repository}`

## 5. 输出契约(精确路径)

- src/frontend/src/api/** 或 src/miniapp/<channel>/api/**
- 返回:封装接口数 + 契约差异报告

## 6. 治理汇报协议(★ 强制)

本技能**必须**向管控体系回报,禁止闷头干完不吭声。回报由 `scripts/governance.py` 承载,回报记录落到 `state/skill-runs.yaml`,Lead 看板可读。

**① 开工登记(第一步就做,未登记视为黑工)**

```bash
python "${CLAUDE_PLUGIN_ROOT}/scripts/governance.py" skill start --skill S04-06-api-client-wrapper \
    --f <覆盖的F-xx,逗号分隔> --task "<本次任务一句话>" \
    --worker <worker-id,并行开发时必填>
# 成功输出 RUN-xxx;未过门禁会 exit 2 并给出缺哪个门禁
```

**② 定时回报进度(执行过程中,不得只在结束时报一次)**

> 回报频率:每完成 1 个文件或每 10 分钟回报一次;超过 30 分钟无心跳由 skill_heartbeat 钩子告警

```bash
python "${CLAUDE_PLUGIN_ROOT}/scripts/governance.py" skill progress --run RUN-xxx --pct 40 --note "<已完成什么>"
python "${CLAUDE_PLUGIN_ROOT}/scripts/governance.py" skill beat    --run RUN-xxx          # 纯心跳,不改百分比
```

**③ 完成汇报结果(收尾必做)**

```bash
python "${CLAUDE_PLUGIN_ROOT}/scripts/governance.py" skill done --run RUN-xxx --status success \
    --summary "<结果摘要>" \
    --files "<产出路径,逗号分隔>" \
    --blockers "<阻塞点,没有就省略>"
# status 可选 success / partial / blocked / failed(引擎统一接受)
# 非 success 必须给 --summary 说明原因,否则 exit 2
```

**④ 汇报后由负责人决定下一步**


汇报完成后,**技能的执行者不得自行决定下一步**。流程为:

```
技能 done ──▶ 管控体系记录结果与产出
             ──▶ Lead 汇总进看板(governance.py skill board)
             ──▶ 负责人(用户 / Lead)判定:
                  ├─ 通过     → 回填 RTM → 推进下一技能或下一阶段
                  ├─ 需返工   → 指定同一或另一 worker 重跑,保留原 RUN 记录
                  ├─ 需变更   → 走 g-change 变更单,重走受影响门禁
                  └─ 已阻塞   → 登记 blocker,升级给用户决策
```

纪律:
- 终态任务**不得**再报进度或重复提交结果(引擎会 exit 1 拒绝)
- 心跳超时由 `skill_heartbeat.py` 钩子在 Stop/PostToolUse 时告警
- 未 `skill start` 就产出文件 = 黑工,Lead 复盘时按违规计

## 多人并行开发规则(本技能强制适用)

- **R1 文件所有权**:动手前 `worker claim --id <worker> --path <文件>`,同一文件同一时刻只归属一个 worker;他人已占用会被 exit 2 拦截;完工用 `worker release` 释放
- **R2 契约先行**:DTO/接口签名/表结构先落地并被全员引用,禁止各自定义同名不同构的对象
- **R3 迁移串行**:数据库迁移脚本序号由引擎串行分配 `worker migration --id <worker> --desc "<说明>"`,禁止手写序号撞号
- **R4 合并顺序**:按 `worker merges` 输出的 M-01 → M-0N 顺序逐个合并,每步跑构建+冒烟,失败只回退该模块不整体回滚
- **并行额度**:developer 同时最多 4 个 worker(超出 register 会被拒,对应 R1 不得超配)
- **冲突检测**:开工前与开工后各跑一次 `worker conflicts`,检出模块/功能点重复认领必须先拆分归属再开工
- **锁总览**:`worker locks` 可查看当前所有文件归属,避免口角

**并行操作命令(照抄即可)**

```bash
# ① 注册 worker(一个开发者一个 id,最多 4 个)
python "${CLAUDE_PLUGIN_ROOT}/scripts/governance.py" worker register --id dev-1 --role developer --module M-01 --f F-01,F-02
# ② 动手前取得文件所有权(R1;他人已占用会 exit 2)
python "${CLAUDE_PLUGIN_ROOT}/scripts/governance.py" worker claim --id dev-1 --path src/backend/payment/service.py
# ③ 开工前后各查一次冲突
python "${CLAUDE_PLUGIN_ROOT}/scripts/governance.py" worker conflicts
# ④ 数据库迁移序号由引擎串行分配(R3)
python "${CLAUDE_PLUGIN_ROOT}/scripts/governance.py" worker migration --id dev-1 --desc "创建缴存台账表"
# ⑤ 合并阶段按 M-01 → M-0N 顺序(R4)
python "${CLAUDE_PLUGIN_ROOT}/scripts/governance.py" worker merges
# ⑥ 随时查看文件归属
python "${CLAUDE_PLUGIN_ROOT}/scripts/governance.py" worker locks
```

> 同一文件被两人同时改是并行开发最常见的破坏来源。动手前先 `worker claim`,他人已占用会被 exit 2 硬拦截,不要试图绕过。

## 7. 必须真实执行的验证命令

**开工前必跑(任一非零退出即停手回报,不得带病执行)**

```bash
python "${CLAUDE_PLUGIN_ROOT}/scripts/governance.py" status
python "${CLAUDE_PLUGIN_ROOT}/scripts/governance.py" gate check G1_input_ready
python "${CLAUDE_PLUGIN_ROOT}/scripts/governance.py" gate check G2_channel_check
python "${CLAUDE_PLUGIN_ROOT}/scripts/governance.py" gate check G3_oss_and_baseline
python "${CLAUDE_PLUGIN_ROOT}/scripts/governance.py" gate check G4_design_review
python "${CLAUDE_PLUGIN_ROOT}/scripts/governance.py" worker list
python "${CLAUDE_PLUGIN_ROOT}/scripts/governance.py" worker conflicts
```

**本技能专项验证**

```bash
执行类型检查/构建
```

**完工后必跑**

```bash
python "${CLAUDE_PLUGIN_ROOT}/scripts/governance.py" status
python "${CLAUDE_PLUGIN_ROOT}/scripts/governance.py" worker conflicts
python "${CLAUDE_PLUGIN_ROOT}/scripts/governance.py" rtm coverage --stage design
```

> 验证命令必须真实运行并把结果回报给用户;只「在脑子里过一遍」视为未执行。

## 8. 完成判据(DoD)

- 只修改了归属本 worker 的文件(worker locks 可查)
- 契约(DTO/接口签名)与 artifacts/stage3-design 完全一致,未擅自变更
- 单元测试随代码提交,且在本机真实跑过
- 写操作都有权限点与数据归属校验(越权防护)
- lint 通过,无新增 warning 级别以上问题

## 9. 交付前自检

- [ ] 出入参与 openapi 一致
- [ ] 错误处理统一
- [ ] mock 可用

## 10. 反例与常见错误(踩过的坑,勿重蹈)

- 两个 worker 同时改同一个文件 —— R1 文件所有权会拦截,先 `worker claim` 再改
- 发现契约有问题就自己改契约 —— 必须走 g-change 变更单
- 单元测试写在脑子里 —— 必须真实执行并把结果贴出来
- 顺手改了别人的模块 —— 跨模块改动一律先走变更单
- 未 register worker 就开工 —— 并行额度与归属无法追踪
- 为图省事保留多余标语 / 说明文字 / 次要标签 —— 页面与界面只保留承载功能的必要信息
- 改动不回归就提交 —— 每次修改须兼顾 UX 与 DX 且回归既有功能主路径,不得破坏现有功能

---

### 铁律(执行本技能期间必须遵守)

1. 前置条件未满足即刻停止并回报,**不得带病执行**
2. 先 `skill start` 登记再动手;过程中定时 `skill progress`;完工 `skill done`
3. 只操作归属于本角色/本 worker 的文件,跨模块改动一律先走 `/g-change`
4. 产物先写 `.draft.md`;对外正式件必须由 `scripts/export.py` 导出 docx/pdf/xlsx,**Markdown 只能作内部草案或台账,不得作为对外交付件**
5. 输出超出需求基线的内容 = 超范围,先 `scope check`,拦截并回到 Lead
6. 门禁确签只能由用户执行(Lead 自签返回 exit 2),第三方审计只能由 change-auditor 执行
7. 本技能执行完毕即收尾:`skill done` 回报 + `/g-status` 校验,由负责人决定下一步

Wersje

W bazie nie ma innych skilli o nazwie s04-06-api-client-wrapper.

Migawka bazy z 13.11.2026 · wersja paczki 863872dcfba1 (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 100sdk-wrapper-creator
    Pomaga tworzyć wrappery SDK i działa automatycznie w kategorii integracji API.
  • 100api-sdk-generator
    Generuje kod SDK klienta, biblioteki wrapperów API, modele żądań i odpowiedzi oraz wzorce użycia w wybranym języku dla dowolnego API REST.
  • 100together-sdk-patterns
    Opakowuje Together AI SDK v2 w typowany adapter z modelami z katalogu, ograniczonymi ponowieniami, normalizacją streamingu i rejestrem zużycia.
  • 100sdk
    Korzysta z backendu @oneie/sdk przez wrapper wtyczki we frontendzie, np. przy odczycie i zapisie danych w trasach API lub SSR.
  • 96s04-05-miniapp-component
    Tworzy strony i własne komponenty mini programu, opakowując wywołania natywnych funkcji.
  • 95youdotcom-api
    Integruje API You.com (Research, Search, Contents) w dowolnym języku przez bezpośrednie wywołania HTTP, bez SDK.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.