项目 API

项目管理相关的 API 端点。

端点概览

方法	端点	描述	认证
POST	/projects	创建项目	✅
GET	/projects	项目列表	✅
GET	/projects/{id}	项目详情	✅
PATCH	/projects/{id}	更新项目	✅
DELETE	/projects/{id}	删除项目	✅

---

创建项目

POST /api/v1/projects

创建新项目。

请求

POST /api/v1/projects
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "My Project",
  "slug": "my-project",
  "description": "Project description"
}

参数说明:

字段	类型	必填	说明
name	string	✅	项目名称（3-100字符）
slug	string	❌	URL友好标识符（自动生成）
description	string	❌	项目描述

Slug 规则:

• 小写字母、数字和连字符
• 自动从 name 生成
• 全局唯一

响应

成功 (201 Created):

{
  "project_id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "My Project",
  "slug": "my-project",
  "description": "Project description",
  "created_at": "2024-01-01T12:00:00Z",
  "updated_at": "2024-01-01T12:00:00Z"
}

错误响应:

• 400 Bad Request: 参数验证失败
• 409 Conflict: Slug 已存在

示例

const createProject = async (name: string, description?: string) => {
  const response = await fetch('/api/v1/projects', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ name, description }),
  });
  
  return response.json();
};

---

项目列表

GET /api/v1/projects

获取当前用户的项目列表。

请求

GET /api/v1/projects?limit=20&offset=0
Authorization: Bearer <token>

查询参数:

参数	类型	默认值	说明
limit	integer	20	每页数量 (1-100)
offset	integer	0	偏移量

响应

成功 (200 OK):

{
  "projects": [
    {
      "project_id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "My Project",
      "slug": "my-project",
      "description": "Project description",
      "created_at": "2024-01-01T12:00:00Z",
      "updated_at": "2024-01-01T12:00:00Z"
    }
  ],
  "total": 1
}

示例

const listProjects = async (limit = 20, offset = 0) => {
  const response = await fetch(
    `/api/v1/projects?limit=${limit}&offset=${offset}`,
    {
      headers: { 'Authorization': `Bearer ${token}` },
    }
  );
  
  return response.json();
};

---

项目详情

GET /api/v1/projects/{id}

获取特定项目的详细信息。

请求

GET /api/v1/projects/550e8400-e29b-41d4-a716-446655440000
Authorization: Bearer <token>

响应

成功 (200 OK):

{
  "project_id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "My Project",
  "slug": "my-project",
  "description": "Project description",
  "created_at": "2024-01-01T12:00:00Z",
  "updated_at": "2024-01-01T12:00:00Z"
}

错误响应:

• 404 Not Found: 项目不存在或无权访问

示例

const getProject = async (projectId: string) => {
  const response = await fetch(`/api/v1/projects/${projectId}`, {
    headers: { 'Authorization': `Bearer ${token}` },
  });
  
  if (!response.ok) {
    throw new Error('Project not found');
  }
  
  return response.json();
};

---

更新项目

PATCH /api/v1/projects/{id}

更新项目信息。

请求

PATCH /api/v1/projects/550e8400-e29b-41d4-a716-446655440000
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "Updated Project Name",
  "slug": "updated-slug",
  "description": "Updated description"
}

参数说明:

字段	类型	必填	说明
name	string	❌	新项目名称
slug	string	❌	新 Slug
description	string/null	❌	新描述（null 清空）

说明:

• 至少提供一个字段
• Slug 需全局唯一

响应

成功 (200 OK):

{
  "project_id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Updated Project Name",
  "slug": "updated-slug",
  "description": "Updated description",
  "created_at": "2024-01-01T12:00:00Z",
  "updated_at": "2024-01-01T13:00:00Z"
}

错误响应:

• 400 Bad Request: 参数验证失败
• 404 Not Found: 项目不存在
• 409 Conflict: Slug 已被使用

示例

const updateProject = async (
  projectId: string,
  updates: { name?: string; slug?: string; description?: string | null }
) => {
  const response = await fetch(`/api/v1/projects/${projectId}`, {
    method: 'PATCH',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(updates),
  });
  
  return response.json();
};

---

删除项目

DELETE /api/v1/projects/{id}

删除项目及其所有关联数据。

请求

DELETE /api/v1/projects/550e8400-e29b-41d4-a716-446655440000
Authorization: Bearer <token>

警告: 此操作会级联删除：

• 项目下的所有仓库
• 所有分析任务
• 所有会话和产物

响应

成功 (204 No Content):

无响应体。

错误响应:

• 404 Not Found: 项目不存在

示例

const deleteProject = async (projectId: string) => {
  const response = await fetch(`/api/v1/projects/${projectId}`, {
    method: 'DELETE',
    headers: { 'Authorization': `Bearer ${token}` },
  });
  
  if (!response.ok) {
    throw new Error('Failed to delete project');
  }
};

---

数据模型

Project 对象

interface Project {
  project_id: string;      // UUID
  name: string;           // 项目名称
  slug: string;           // URL标识符
  description?: string;   // 项目描述
  created_at: string;     // ISO 8601 时间戳
  updated_at: string;     // ISO 8601 时间戳
}

---

最佳实践

1. Slug 管理

// 自动生成 Slug
const generateSlug = (name: string): string => {
  return name
    .toLowerCase()
    .trim()
    .replace(/[^\w\s-]/g, '')
    .replace(/[\s_-]+/g, '-')
    .replace(/^-+|-+$/g, '');
};

// 创建时让后端生成
const project = await createProject('My Project'); // slug 自动生成

2. 错误处理

try {
  await createProject(name, description);
} catch (error) {
  if (error.response?.status === 409) {
    // Slug 冲突，尝试添加后缀
    await createProject(name, description);
  }
}

3. 列表分页

const fetchAllProjects = async () => {
  const limit = 50;
  let offset = 0;
  const allProjects = [];
  
  while (true) {
    const { projects, total } = await listProjects(limit, offset);
    allProjects.push(...projects);
    
    if (allProjects.length >= total) break;
    offset += limit;
  }
  
  return allProjects;
};

---

相关端点

• 仓库 API - 项目下的仓库管理
• 分析 API - 项目分析任务
• 集成 API - GitHub 集成

---

相关文档

• API 概览
• 架构：模块划分