返回

API 接口管理平台

项目2025年1月6日6

一个全功能的 API 管理平台，帮助团队更好地设计、测试和监控 API 接口。

项目背景

在团队开发中，API 文档管理、接口测试和监控往往需要多个工具。这个平台整合了所有功能，提供一站式解决方案。

技术架构

前端技术栈

  • Vue 3: Composition API
  • Vite: 快速构建工具
  • Element Plus: UI 组件库
  • Monaco Editor: 代码编辑器
  • Echarts: 数据可视化

后端技术栈

  • Node.js: 运行时环境
  • Express: Web 框架
  • MongoDB: 文档数据库
  • Socket.io: 实时通信
  • JWT: 用户认证

核心功能模块

1. API 文档管理

支持 OpenAPI 3.0 规范，自动生成文档：

// API 接口定义
interface ApiEndpoint {
  id: string;
  project: string;
  path: string;
  method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
  summary: string;
  description: string;
  parameters: Parameter[];
  requestBody?: RequestBody;
  responses: Response[];
  tags: string[];
}

// 文档生成器
class DocGenerator {
  generateMarkdown(api: ApiEndpoint): string {
    let md = `## ${api.summary}\n\n`;
    md += `${api.method} ${api.path}\n\n`;
    md += `### 描述\n${api.description}\n\n`;

    if (api.parameters.length > 0) {
      md += `### 参数\n`;
      md += `| 参数名 | 类型 | 必填 | 说明 |\n`;
      md += `| --- | --- | --- | --- |\n`;
      api.parameters.forEach(param => {
        md += `| ${param.name} | ${param.type} | ${param.required ? '是' : '否'} | ${param.description} |\n`;
      });
    }

    return md;
  }
}

2. 在线接口测试

内置 HTTP 客户端，支持发送各种请求：

<!-- ApiTester.vue -->
<script setup lang="ts">
import { ref } from 'vue';

const request = ref({
  method: 'GET',
  url: '',
  headers: {},
  params: {},
  body: null,
});

const response = ref(null);
const loading = ref(false);

async function sendRequest() {
  loading.value = true;
  try {
    const res = await fetch(request.value.url, {
      method: request.value.method,
      headers: request.value.headers,
      body: request.value.body ? JSON.stringify(request.value.body) : undefined,
    });

    const data = await res.json();
    response.value = {
      status: res.status,
      headers: Object.fromEntries(res.headers.entries()),
      data,
    };
  } catch (error) {
    response.value = { error: error.message };
  } finally {
    loading.value = false;
  }
}
</script>

<template>
  <div class="api-tester">
    <div class="request-form">
      <select v-model="request.method">
        <option>GET</option>
        <option>POST</option>
        <option>PUT</option>
        <option>DELETE</option>
      </select>

      <input
        v-model="request.url"
        placeholder="https://api.example.com/users"
        type="url"
      />

      <button @click="sendRequest" :disabled="loading">
        {{ loading ? '发送中...' : '发送请求' }}
      </button>
    </div>

    <!-- 参数编辑器 -->
    <div class="params-editor">
      <h3>Headers</h3>
      <KeyValueEditor v-model="request.headers" />

      <h3>Query Parameters</h3>
      <KeyValueEditor v-model="request.params" />

      <h3>Body</h3>
      <MonacoEditor
        v-model="request.body"
        language="json"
        height="200px"
      />
    </div>

    <!-- 响应显示 -->
    <div v-if="response" class="response">
      <div class="response-status">
        Status: {{ response.status }}
      </div>

      <MonacoEditor
        :value="JSON.stringify(response.data, null, 2)"
        language="json"
        readOnly
      />
    </div>
  </div>
</template>

3. Mock 服务

自动生成 Mock 数据：

// Mock 服务
class MockService {
  generateMock(schema: any): any {
    if (schema.type === 'object') {
      const result: any = {};
      for (const [key, value] of Object.entries(schema.properties)) {
        result[key] = this.generateMock(value);
      }
      return result;
    }

    if (schema.type === 'array') {
      return [this.generateMock(schema.items)];
    }

    if (schema.type === 'string') {
      return this.mockString(schema.format || 'text');
    }

    if (schema.type === 'number') {
      return Math.floor(Math.random() * 1000);
    }

    if (schema.type === 'boolean') {
      return Math.random() > 0.5;
    }
  }

  mockString(format: string): string {
    const mocks = {
      email: () => `user${Math.floor(Math.random() * 1000)}@example.com`,
      date: () => new Date().toISOString(),
      uuid: () => crypto.randomUUID(),
      name: () => ['Alice', 'Bob', 'Charlie'][Math.floor(Math.random() * 3)],
    };

    return mocks[format]?.() || 'sample text';
  }
}

4. 接口监控

实时监控 API 性能：

// 监控服务
class MonitorService {
  async recordRequest(req: ApiRequest) {
    const startTime = Date.now();

    // 记录请求
    await db.collection('api_logs').insertOne({
      ...req,
      timestamp: new Date(),
      status: 'pending',
    });

    return {
      async complete(res: ApiResponse) {
        const duration = Date.now() - startTime;

        await db.collection('api_logs').updateOne(
          { _id: req.id },
          {
            $set: {
              status: res.status < 400 ? 'success' : 'error',
              duration,
              response: res,
            },
          }
        );

        // 性能异常告警
        if (duration > 3000) {
          this.sendAlert({
            type: 'slow_api',
            endpoint: req.path,
            duration,
          });
        }
      },
    };
  }

  getStatistics(project: string, timeRange: DateRange) {
    return db.collection('api_logs').aggregate([
      {
        $match: {
          project,
          timestamp: { $gte: timeRange.start, $lte: timeRange.end },
        },
      },
      {
        $group: {
          _id: '$path',
          avgDuration: { $avg: '$duration' },
          totalRequests: { $sum: 1 },
          errorRate: {
            $avg: { $cond: [{ $eq: ['$status', 'error'] }, 1, 0] },
          },
        },
      },
    ]);
  }
}

5. 团队协作

支持多人协作管理 API：

// 权限管理
enum Permission {
  READ = 'read',
  WRITE = 'write',
  DELETE = 'delete',
  ADMIN = 'admin',
}

interface TeamMember {
  userId: string;
  role: 'owner' | 'editor' | 'viewer';
  permissions: Permission[];
}

// 实时协作
function setupWebSocket(projectId: string) {
  const socket = io(`/projects/${projectId}`);

  socket.on('api_updated', (data) => {
    // 实时更新 API 文档
    updateApiInStore(data);
  });

  socket.on('user_joined', (user) => {
    showNotification(`${user.name} 加入了协作`);
  });

  return socket;
}

界面展示

仪表板

<!-- Dashboard.vue -->
<script setup lang="ts">
import { ref, onMounted } from 'vue';
import * as echarts from 'echarts';

const chartRef = ref<HTMLElement>();

onMounted(() => {
  const chart = echarts.init(chartRef.value!);

  chart.setOption({
    title: { text: 'API 调用统计' },
    tooltip: {},
    xAxis: {
      data: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun'],
    },
    yAxis: {},
    series: [{
      type: 'line',
      data: [120, 200, 150, 80, 70, 110, 130],
    }],
  });
});
</script>

<template>
  <div class="dashboard">
    <div class="stats-cards">
      <StatCard title="总接口数" :value="1234" />
      <StatCard title="今日调用" :value="56789" />
      <StatCard title="平均响应时间" :value="245" unit="ms" />
      <StatCard title="错误率" :value="0.12" unit="%" />
    </div>

    <div ref="chartRef" class="chart" style="height: 400px"></div>
  </div>
</template>

部署方案

Docker 容器化

# Dockerfile
FROM node:18-alpine

WORKDIR /app

# 安装依赖
COPY package*.json ./
RUN npm ci

# 构建应用
COPY . .
RUN npm run build

EXPOSE 3000

CMD ["npm", "start"]
# docker-compose.yml
version: '3.8'
services:
  app:
    build: .
    ports:
      - "3000:3000"
    environment:
      - MONGODB_URI=mongodb://mongo:27017/api-platform
    depends_on:
      - mongo

  mongo:
    image: mongo:6
    volumes:
      - mongo-data:/data/db

volumes:
  mongo-data:

项目亮点

1. 全功能集成

  • API 文档
  • 接口测试
  • Mock 服务
  • 性能监控
  • 团队协作

2. 开发体验

  • 代码提示
  • 语法高亮
  • 格式验证
  • 版本对比

3. 性能优化

  • 虚拟滚动
  • 懒加载
  • 代码分割
  • 缓存策略

使用效果

团队效率提升

  • 📝 文档编写时间减少 60%
  • 🧪 测试效率提升 3 倍
  • 🐛 问题定位速度提升 50%
  • 👥 协作沟通成本降低 40%

技术难点

1. 实时协作冲突解决

// 使用 Operational Transformation 解决冲突
class OTResolver {
  transform(operation1: Operation, operation2: Operation): Operation {
    // 实现操作转换算法
    // 确保并发操作能正确合并
  }
}

2. 大量数据处理

// 使用虚拟滚动处理大量数据
import { VirtualList } from 'vue-virtual-scroll-list';

<VirtualList
  :data-sources="apiList"
  :data-key="'id'"
  :keeps="30"
>
  <template #default="{ item }">
    <ApiItem :api="item" />
  </template>
</VirtualList>

未来规划

  • 支持 GraphQL
  • WebSocket 接口测试
  • 接口自动化测试
  • CI/CD 集成
  • 性能测试工具
  • 多语言支持
Vue3Node.jsMongoDBAPI
600