API 接口设计模块使用手册

# 标准请求格式
POST /api/v1/users
Content-Type: application/json
Authorization: Bearer {token}

{
  "data": {
    "username": "john_doe",
    "email": "john@example.com",
    "role": "developer"
  },
  "meta": {
    "requestId": "req_123456",
    "timestamp": "2026-03-13T10:30:00Z"
  }
}

# 标准响应格式
{
  "success": true,
  "data": {
    "id": "usr_789",
    "username": "john_doe",
    "createdAt": "2026-03-13T10:30:00Z"
  },
  "meta": {
    "requestId": "req_123456",
    "timestamp": "2026-03-13T10:30:01Z"
  }
}

# 错误响应格式
{
  "success": false,
  "error": {
    "code": "USER_ALREADY_EXISTS",
    "message": "用户名已存在",
    "details": {
      "field": "username",
      "value": "john_doe"
    }
  },
  "meta": {
    "requestId": "req_123456",
    "timestamp": "2026-03-13T10:30:01Z"
  }
}

# OpenClaw 配置文件示例 (openclaw.yaml)
version: "2.0"
project:
  name: "用户管理系统"
  spec: "./specs/api.yaml"
  
generators:
  backend:
    language: "python"
    framework: "fastapi"
    output: "./backend/src"
  
  frontend:
    language: "typescript"
    framework: "react"
    output: "./frontend/src/api"
  
  tests:
    type: "integration"
    framework: "pytest"
    output: "./tests/integration"

mock:
  enabled: true
  port: 8080
  delay: "random(100, 500)"
  
validation:
  strict_mode: true
  schema_validation: true

# 初始化项目
$ openclaw init --template rest-api

# 生成接口定义
$ openclaw generate spec --from-prd ./prd.md

# 启动 Mock 服务
$ openclaw mock start --spec ./specs/api.yaml

# 生成代码
$ openclaw generate code --config openclaw.yaml

# 运行测试
$ openclaw test --spec ./specs/api.yaml --coverage

# 验证契约
$ openclaw validate contract --impl ./backend --spec ./specs/api.yaml

# 系统 Prompt 示例
You are an expert backend developer specializing in API implementation.
Given the following OpenAPI specification, generate production-ready code.

Requirements:
1. Follow RESTful best practices
2. Implement proper error handling
3. Add comprehensive input validation
4. Include detailed docstrings
5. Write unit tests for each endpoint
6. Ensure security best practices (authentication, authorization, rate limiting)

API Specification:
{api_spec_json}

Business Logic:
{business_logic_description}

Generate code for: FastAPI (Python) / Express (Node.js) / Spring Boot (Java)

# 人工反馈示例 (通过 Web 界面提交)
{
  "reviewId": "rev_001",
  "artifactType": "api_design",
  "comments": [
    {
      "line": 45,
      "type": "suggestion",
      "message": "建议将此接口的分页参数改为 cursor-based 分页，提升性能",
      "priority": "medium"
    },
    {
      "line": 78,
      "type": "correction",
      "message": "此字段的验证规则不完整，需要增加长度限制",
      "priority": "high"
    }
  ],
  "status": "pending_revision"
}

# AI 自动响应并迭代
{
  "revisionId": "rev_001_v2",
  "changes": [
    {
      "addressedComment": 1,
      "action": "modified",
      "description": "已将分页方式改为 cursor-based，添加了 cursor 和 limit 参数"
    },
    {
      "addressedComment": 2,
      "action": "modified",
      "description": "已添加 username 字段长度验证 (3-20 字符)"
    }
  ],
  "status": "ready_for_review"
}

# Jenkinsfile 示例
pipeline {
    agent any
    
    environment {
        DOCKER_REGISTRY = 'registry.example.com'
        KUBE_CONFIG = credentials('kube-config')
    }
    
    stages {
        stage('Checkout') {
            steps {
                git branch: 'main', url: 'https://github.com/org/repo.git'
            }
        }
        
        stage('API Validation') {
            steps {
                sh 'openclaw validate contract --spec ./specs/api.yaml'
            }
        }
        
        stage('Unit Test') {
            steps {
                sh 'pytest tests/unit --cov=src --cov-report=xml'
                junit 'test-results/**/*.xml'
            }
        }
        
        stage('Integration Test') {
            steps {
                sh 'docker-compose up -d && pytest tests/integration'
            }
        }
        
        stage('Build Docker Image') {
            steps {
                script {
                    docker.build("${DOCKER_REGISTRY}/app:${BUILD_NUMBER}")
                }
            }
        }
        
        stage('Deploy to K8S') {
            steps {
                sh 'kubectl apply -f k8s/deployment.yaml'
                sh 'kubectl rollout status deployment/app'
            }
        }
        
        stage('UI E2E Test') {
            steps {
                sh 'playwright test --reporter=html'
            }
        }
    }
    
    post {
        always {
            cleanWs()
        }
        success {
            slackSend channel: '#deployments', 
                      message: "✅ Deployment successful: ${BUILD_URL}"
        }
        failure {
            slackSend channel: '#alerts', 
                      message: "❌ Deployment failed: ${BUILD_URL}"
        }
    }
}

# Kubernetes Deployment (k8s/deployment.yaml)
apiVersion: apps/v1
kind: Deployment
metadata:
  name: user-service
  namespace: production
spec:
  replicas: 3
  selector:
    matchLabels:
      app: user-service
  template:
    metadata:
      labels:
        app: user-service
    spec:
      containers:
      - name: api
        image: registry.example.com/app:latest
        ports:
        - containerPort: 8080
        env:
        - name: DATABASE_URL
          valueFrom:
            secretKeyRef:
              name: db-secret
              key: url
        resources:
          requests:
            memory: "256Mi"
            cpu: "250m"
          limits:
            memory: "512Mi"
            cpu: "500m"
        livenessProbe:
          httpGet:
            path: /health
            port: 8080
          initialDelaySeconds: 30
          periodSeconds: 10
---
apiVersion: v1
kind: Service
metadata:
  name: user-service
spec:
  selector:
    app: user-service
  ports:
  - port: 80
    targetPort: 8080
  type: ClusterIP