ProjectAGiPrompt/91-HarnessEngineering/1-API自动更新Postman/2-Go项目同步实现方案.md

基本信息如下

1. Postman API KEY: PMAK-6a3cc4b60d07e1000174ede8-e51652fd3ba3f4a2895f1386a8b317ebf1
2. collection uid: 15340181-95b85065-2cf9-4ebe-bde2-e76fbfdeeea9

推荐方案是：方案二（swag + openapi-to-postmanv2 + Git pre-commit hook + Postman API 自动推送）的完整自动化流水线，

---

三种方案可行性分析

维度	方案一：Postman MCP Server	方案二：OpenAPI 转换流水线	方案三：大模型控制 Postman API
稳定性	⚠️ MCP 协议仍在快速变化，Postman MCP Server 尚不成熟	✅ 工具链稳定，swag+openapi-to-postmanv2 均为生产可用	❌ 大模型调用有延迟、不确定性，不适合自动化 CI
Gin 原生支持	❌ 无法感知路由，需手动描述	✅ swag 直接解析 Gin 路由注解，完全自动化	❌ 需要额外描述路由结构
增量同步	⚠️ 依赖 MCP 协议实现，Collection 合并逻辑不透明	✅ Postman PUT API 覆盖 Collection，配合 folderStrategy=Tags 保持结构	❌ 无法保证增量一致性
Windows 兼容	❌ Codex 在 Windows 下配置复杂	✅ npm + swag CLI 在 Windows 完全支持	⚠️ 依赖 API 密钥，可行但复杂
离线可用	❌ 依赖 Codex 云端服务	✅ 除推送 Postman API 外完全本地	❌ 必须联网

---

推荐方案：OpenAPI 自动化流水线

整体流程为：

git commit
    ↓ pre-commit hook
swag init (生成 swagger.json)
    ↓
openapi2postmanv2 (转换为 collection.json)
    ↓
curl PUT Postman API (推送到 Postman Collection)
    ↓
git commit 完成

---

具体实施步骤

Step 1：安装依赖工具

# 安装 swag（Go OpenAPI 注解生成器）
go install github.com/swaggo/swag/cmd/swag@latest

# 安装 Gin swagger 中间件
go get -u github.com/swaggo/gin-swagger
go get -u github.com/swaggo/files

# 安装 openapi-to-postmanv2（需要 Node.js）
npm install -g openapi-to-postmanv2

Step 2：在 Gin 路由上添加 swag 注解

在 main.go 中添加全局文档注解 ： medium

// @title           My API
// @version         1.0
// @description     API 文档
// @host            localhost:8080
// @BasePath        /api/v1
package main

import (
    _ "your-project/docs" // swag 生成的 docs 包
    ginSwagger "github.com/swaggo/gin-swagger"
    swaggerFiles "github.com/swaggo/files"
    "github.com/gin-gonic/gin"
)

func main() {
    r := gin.Default()
    r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
    // ... 路由注册
    r.Run()
}

在具体 Handler 函数上添加接口注解：

// GetUser 获取用户信息
// @Summary      获取用户
// @Description  通过 ID 获取用户详情
// @Tags         users
// @Accept       json
// @Produce      json
// @Param        id   path      int     true  "User ID"
// @Success      200  {object}  UserResponse
// @Failure      404  {object}  ErrorResponse
// @Router       /users/{id} [get]
func GetUser(c *gin.Context) {
    // ...
}

Step 3：配置 Git pre-commit hook

在项目根目录创建 .git/hooks/pre-commit 文件（Windows 下可创建 pre-commit 无扩展名文件）： richardswinbank

#!/bin/sh
# pre-commit: 自动生成 OpenAPI -> 转换 -> 推送 Postman

set -e

echo "[hook] 正在生成 swagger 文档..."
swag init --generalInfo cmd/main.go --output docs

echo "[hook] 正在转换为 Postman Collection..."
openapi2postmanv2 -s docs/swagger.json \
  -o docs/postman_collection.json \
  -p \
  -O folderStrategy=Tags,includeAuthInfoInExample=true

echo "[hook] 正在推送到 Postman..."
# POSTMAN_API_KEY 和 POSTMAN_COLLECTION_UID 通过环境变量注入
node scripts/update-postman.js

# 将生成的文档文件加入本次提交
git add docs/swagger.json docs/swagger.yaml docs/postman_collection.json
echo "[hook] API 文档已自动更新并加入提交"

Step 4：创建 Postman 推送脚本

创建 scripts/update-postman.js ： community.postman

const fs = require('fs');
const https = require('https');

const POSTMAN_API_KEY = process.env.POSTMAN_API_KEY;
const COLLECTION_UID = process.env.POSTMAN_COLLECTION_UID;

if (!POSTMAN_API_KEY || !COLLECTION_UID) {
    console.error('缺少环境变量: POSTMAN_API_KEY 或 POSTMAN_COLLECTION_UID');
    process.exit(1);
}

const collectionData = JSON.parse(
    fs.readFileSync('./docs/postman_collection.json', 'utf8')
);

// Postman API 要求 collection 包装在 { collection: ... } 中
const body = JSON.stringify({ collection: collectionData });

const options = {
    hostname: 'api.getpostman.com',
    path: `/collections/${COLLECTION_UID}`,
    method: 'PUT',
    headers: {
        'Content-Type': 'application/json',
        'X-Api-Key': POSTMAN_API_KEY,
        'Content-Length': Buffer.byteLength(body)
    }
};

const req = https.request(options, (res) => {
    let data = '';
    res.on('data', chunk => data += chunk);
    res.on('end', () => {
        const result = JSON.parse(data);
        if (res.statusCode === 200) {
            console.log(`✅ Postman Collection 更新成功: ${result.collection?.name}`);
        } else {
            console.error(`❌ 更新失败 (${res.statusCode}):`, data);
            process.exit(1);
        }
    });
});

req.on('error', (e) => { console.error('请求错误:', e); process.exit(1); });
req.write(body);
req.end();

Step 5：配置环境变量（Windows）

# 在 PowerShell 中设置用户级环境变量（持久化）
[System.Environment]::SetEnvironmentVariable(
    "POSTMAN_API_KEY", "your_api_key_here", "User"
)
[System.Environment]::SetEnvironmentVariable(
    "POSTMAN_COLLECTION_UID", "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "User"
)

获取 Collection UID 的方法：在 Postman 桌面端右键点击 Collection → Copy link 或 Info，URL 中的 UUID 即为 UID。获取 API Key：Postman → 头像 → Settings → API Keys → Generate API Key 。 community.postman

---

进阶优化：仅在 .go 文件变更时触发

将 pre-commit 脚本中的触发逻辑改为仅当有 Go 文件变更时执行，避免无意义的推送：

#!/bin/sh
# 检查是否有 .go 文件变更
GO_FILES=$(git diff --cached --name-only --diff-filter=ACM | grep '\.go$')

if [ -z "$GO_FILES" ]; then
    echo "[hook] 无 .go 文件变更，跳过 API 文档更新"
    exit 0
fi

# ... 后续 swag init、转换、推送逻辑

---