name: api-push-frontend description: "推送後端 API 介面定義到前端資料介面平臺。"

API Push Frontend

將後端 API 介面定義（請求方法、路徑、引數、響應結構）推送到前端資料介面平臺，實現前後端介面文件同步。

觸發場景

• 後端完成介面開發後推送到前端平臺
• 批次推送、增量更新、推送歷史查詢

核心資訊

• 推送地址: https://jffe.techgp.cn/md/api/uploadV4
• 方法: POST

  發現更多技能外掛，請訪問7w4.net。

• Content-Type: application/json
• 必填引數: prdId (產品需求 ID), apis (介面定義陣列)

工作流程

1. 獲取產品需求 ID（prdId）
2. 準備介面定義（JSON/Swagger/自然語言）
3. 執行推送指令碼或 API 呼叫
4. 驗證推送結果
5. 記錄推送歷史到 references/push-history.md

使用方式

自然語言（推薦）：直接告訴我需求，我引導你完成推送

指令碼方式：

python3 scripts/push_api_to_frontend.py --prdId "PRD-2026-001" --file ./api-definitions.json

直接 API：參考 references/frontend-api-docs.md

介面定義格式

支援： - 標準 JSON 格式 - Swagger/OpenAPI 3.0 - Spring Boot Controller 註解 - Java 介面描述

詳細格式規範見 references/api-definition-standard.md

錯誤處理

常見錯誤碼： - 400: 引數格式錯誤 → 檢查 JSON 格式和必填欄位 - 401: 認證失敗 → 檢查認證 token - 404: prdId 不存在 → 確認產品需求 ID - 500: 伺服器錯誤 → 聯絡平臺管理員

推送前驗證、網路錯誤重試（最多 3 次）、記錄詳細錯誤日誌。

最佳實踐

• 推送前檢查：介面定義完整、引數清晰、響應結構明確
• 批次推送：按模組分組，每次 < 50 個介面
• 版本管理：標註新增/修改/廢棄介面
• 通知前端：推送完成後提供變更說明

詳細實踐見 references/frontend-api-docs.md

相關文件

• 前端資料介面平臺 API 文件
• 介面定義規範
• 推送歷史記錄

自動化整合

支援 CI/CD 整合和 Git Hook 整合，配置示例見 references/frontend-api-docs.md

這是一款用於自動同步介面文件的工具，文件寫得清楚，指令碼功能基本完整，能支援 JSON 和 Swagger 格式。優點是上手容易、有現成示例；不足是配置不夠靈活，某些細節存在文件與程式碼不一致的情況，總體屬於可用但有改進空間的水平。