القائمة
يُحدَّد Prompt الذي يراجع المصدر أولًا بشكل افتراضي. يمكنك التبديل إلى أمر مباشر أو تنزيل نسخة محلية.
اقرأ SKILL.md وأي ملفات مرافقة يعرضها SkillsMP قبل أن تقرر التثبيت.
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
يتجاوز الأمر المباشر Prompt المخصّص للمراجعة. افحص المصدر قبل تشغيله.
npx skills add https://github.com/bage2014/study --skill common-contract-generationيبقى الأمر في سطر واحد. مرّر أفقيًا لمراجعته كاملًا قبل النسخ.
تفضّل نسخة محلية؟ نزّل الملفات المتاحة حاليًا لدى SkillsMP.
استنادا إلى تصنيف SOC المهني
عرض SKILL.md
| name | common-contract-generation |
| description | 契约生成技能，提供API契约文档的生成和管理能力 |
| trigger | 需要定义API接口契约时 |
| disable-when | 项目已有完善的API契约或使用其他契约工具 |
| category | backend |
| tags | ["api","contract","swagger","openapi"] |
提供 API 契约文档的生成和管理能力，帮助团队定义和维护服务间的接口契约，确保前后端协作的一致性。
在以下情况调用此技能：
| 参数 | 类型 | 必填 |
|---|
| 说明 |
|---|
| apiName | String | 是 | API 名称 |
| endpoints | List<Endpoint> | 是 | 接口端点列表 |
| format | String | 否 | 输出格式（openapi3/swagger2） |
| version | String | 否 | API 版本 |
{
"status": "SUCCESS",
"apiName": "用户服务 API",
"version": "1.0.0",
"openapiSpec": "OpenAPI YAML/JSON 规范",
"endpoints": [
{
"path": "/api/users",
"method": "GET",
"summary": "获取用户列表",
"request": {},
"response": {}
}
],
"validationResult": {
"valid": true,
"errors": []
},
"generatedFiles": ["openapi.yaml", "client-sdk.ts"]
}
需求分析 → 接口设计 → 契约编写 → 契约验证 → 文档生成 → SDK生成 → Mock生成
| 检查项 | 说明 | 状态 |
|---|---|---|
| 路径规范 | API 路径是否符合 REST 规范 | ✅/❌ |
| HTTP方法 | 是否使用正确的 HTTP 方法 | ✅/❌ |
| 参数完整 | 请求参数是否完整定义 | ✅/❌ |
| 响应定义 | 响应结构是否完整定义 | ✅/❌ |
| 错误处理 | 是否定义错误响应 | ✅/❌ |
| 状态码 | HTTP 状态码是否正确使用 | ✅/❌ |
| 版本管理 | 是否有版本控制策略 | ✅/❌ |
| 文档完整 | 是否有必要的描述和示例 | ✅/❌ |
openapi: 3.0.3
info:
title: 用户服务 API
description: 用户管理相关接口
version: 1.0.0
servers:
- url: https://api.example.com/v1
paths:
/users:
get:
summary: 获取用户列表
description: 获取所有用户的列表
parameters:
- name: page
in: query
description: 页码
required: false
schema:
type: integer
default: 1
responses:
'200':
description: 成功获取用户列表
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/User'
pagination:
$ref: '#/components/schemas/Pagination'
components:
schemas:
User:
type: object
properties:
id:
type: string
format: uuid
email:
type: string
format: email
name:
type: string
required:
- id
- email
/api/user-profilescomponents:
schemas:
ErrorResponse:
type: object
properties:
code:
type: string
description: 错误代码
message:
type: string
description: 错误消息
details:
type: array
items:
type: string
description: 详细错误信息
required:
- code
- message
| 策略 | 说明 | 适用场景 |
|---|---|---|
| URL 版本 | /v1/users | 简单直接，便于调试 |
| Header 版本 | Accept-Version: 1.0 | 保持 URL 简洁 |
| Media Type 版本 | Accept: application/vnd.example.v1+json | 符合 REST 最佳实践 |
| 组件 | 职责 | 描述 |
|---|---|---|
| ContractDesigner | 契约设计器 | 设计 API 接口契约 |
| SpecGenerator | 规范生成器 | 生成 OpenAPI 规范 |
| ContractValidator | 契约验证器 | 验证契约一致性 |
| SdkGenerator | SDK 生成器 | 生成客户端 SDK |
| MockGenerator | Mock 生成器 | 生成 Mock 数据 |
| 变量名 | 说明 | 默认值 |
|---|---|---|
| CONTRACT_FORMAT | 默认输出格式 | openapi3 |
| API_VERSION | 默认 API 版本 | 1.0.0 |
contract:
format: openapi3
version: 1.0.0
output:
spec: openapi.yaml
docs: docs/api
sdk:
- language: typescript
output: src/client
- language: java
output: client/java