Files
community/docs/api.md
T
2026-10-14 10:26:20 +08:00

38 KiB
Raw Blame History

Community 前端接口对接文档

供社区列表、项目详情、登录、我的工作区和在线文件编辑页面使用。前端通过 Community 后端完成所有业务操作;登录 Token 是平台 Token,前端不连接 Gitea、不持有 Gitea 凭据。

当前支持项目、文件、目录、提交、手动发布、快照 Fork、评论和点赞。项目发布后,后续提交只更新工作区,需要再次调用发布接口才更新社区代码。没有服务端草稿保存、AI 检索、独立工作区实体或项目类型表。

阅读导航

接入约定

地址和请求头

本机默认后端地址为 http://localhost:8993,接口前缀为 /api。实际端口可由 SERVER_PORT 或 PORT 覆盖,部署环境地址由后端提供。

项目 约定
JSON 请求 Content-Type: application/json
登录凭据 Authorization: Bearer <平台 token>,注意 Bearer 的大小写和空格
上传 multipart/form-data,浏览器使用 FormData,不手动设置 Content-Type
业务标识 使用 projectCode、commentCode、userCode,不使用数据库 ID
接口调试 /swagger-ui.html
OpenAPI /v3/api-docs

当前后端没有配置跨域白名单。开发时通过前端开发服务器代理 /api,部署时通过同域反向代理访问;仅允许 OPTIONS 请求不代表已经支持浏览器跨域访问。

统一响应

除成功的文件下载外,响应为以下 JSON 结构。所有成功接口使用 HTTP 200,创建、删除、退出登录也不返回 201 或 204。

{
  "code": "OK",
  "message": "成功",
  "data": null,
  "requestId": "44444444444444444444444444444444"
}
字段 类型 说明
code string 成功为 OK,失败为业务错误码
message string 可用于提示用户,不要通过中文 message 判断错误类型
data 对象、数组或 null 成功数据;失败通常为 null,部分仓库错误包含 projectCode
requestId string 本次请求的排查标识,与响应头 X-Request-Id 一致

下面标为“data 示例”的代码块只展示 data,实际响应仍有上面的包装。示例业务编码和 SHA 均为虚构,调用时必须使用接口返回的真实值。

分页接口的 data 为:

{
  "items": [],
  "page": 1,
  "size": 20,
  "total": 0
}

page 从 1 开始,范围为 1~100000;size 默认 20,范围为 1~100。total 为数字,不返回额外的 pages 字段。空列表是 items: []。

时间和版本

项目和评论的时间字段按 UTC 保存,JSON 格式为 2026-10-13T08:30:00,可能带小数秒,没有时区后缀。前端解析这些字段时应按 UTC 处理,再转换成用户时区;不要直接当成本地时间。历史提交的 authorDate 来自仓库服务,可带 Z 或时区偏移。

Git SHA 使用完整的 40 或 64 位十六进制字符串,不使用缩写。几个版本字段的用途不同:

字段 来源 用途
commitSha 目录、文件、提交结果、历史提交 读取指定版本;提交结果中的值是新版本
expectedCommitSha 提交请求 编辑或上传所基于的工作区版本,防止覆盖其他提交
publishedCommitSha 项目详情 社区当前发布版本;Fork 时原样提交此值
blobSha 文件或目录条目 文件或目录对应的 Git 对象标识,前端不用它提交文件

项目详情不包含工作区当前 main 的 SHA。进入编辑器、提交或发布前,从工作区目录或文件接口获取 commitSha。

接口总览

“可选登录”表示匿名也能访问;带有效 Token 时项目响应可返回当前用户的 liked 状态。公开接口携带已失效的 Bearer Token 仍会返回 401。

方法 路径 登录 成功 data
GET /api/auth/captcha 否 Captcha
POST /api/auth/login 否 Login
POST /api/auth/logout 是 null
GET /api/users/me 是 User
GET /api/project-types 否 ProjectType[]
GET /api/workspace/projects 是 PageResult<Project>
POST /api/workspace/projects 是 Project
GET /api/workspace/projects/{projectCode} 是 Project
PATCH /api/workspace/projects/{projectCode} 是 Project
DELETE /api/workspace/projects/{projectCode} 是 null
GET /api/workspace/projects/{projectCode}/tree 是 Tree
GET /api/workspace/projects/{projectCode}/files 是 ProjectFile 或下载二进制
POST /api/workspace/projects/{projectCode}/commits 是 Commit
GET /api/workspace/projects/{projectCode}/commits 是 PageResult<HistoryEntry>
POST /api/workspace/projects/{projectCode}/uploads/commit 是 Commit
PUT /api/workspace/projects/{projectCode}/publication 是 Project
DELETE /api/workspace/projects/{projectCode}/publication 是 null
GET /api/community/projects 可选 PageResult<Project>
GET /api/community/projects/{projectCode} 可选 Project
GET /api/community/projects/{projectCode}/tree 可选 Tree
GET /api/community/projects/{projectCode}/files 可选 ProjectFile 或下载二进制
POST /api/community/projects/{projectCode}/forks 是 Project
GET /api/community/projects/{projectCode}/comments 可选 PageResult<Comment>
POST /api/community/projects/{projectCode}/comments 是 Comment
DELETE /api/comments/{commentCode} 是 null
PUT /api/community/projects/{projectCode}/like 是 null
DELETE /api/community/projects/{projectCode}/like 是 null

响应数据结构

以下 TypeScript 类型与当前 JSON 字段对应。项目列表、工作区详情、社区详情、创建、修改、发布和 Fork 共用 Project 结构。

/** 无时区后缀,按 UTC 解释。 */
export type UtcDateTime = string;

export interface ApiResponse<T> {
  code: string;
  message: string;
  data: T | null;
  requestId: string;
}

export interface PageResult<T> {
  items: T[];
  page: number;
  size: number;
  total: number;
}

export interface PublicUser {
  userCode: string | null; // 用户记录不可用时可能为 null
  nickname: string;
}

export interface User {
  userCode: string;
  nickname: string;
  email: string;
}

export interface Captcha {
  captchaCode: string;
  image: string; // PNG data URL,可直接作为 img 的 src
  expiresIn: number; // 秒
}

export interface Login {
  token: string;
  tokenType: 'Bearer';
  expiresIn: number; // 秒
  user: User;
}

export interface ProjectType {
  code: string;
  name: string;
}

export interface Project {
  projectCode: string;
  name: string;
  description: string;
  projectType: string;
  owner: PublicUser;
  repoStatus: 'CREATING' | 'READY' | 'FAILED';
  publishStatus: 'UNPUBLISHED' | 'PUBLISHED';
  publishedCommitSha: string | null;
  publishedAt: UtcDateTime | null;
  sourceProjectCode: string | null;
  sourceCommitSha: string | null;
  likeCount: number;
  commentCount: number;
  liked: boolean;
  createdAt: UtcDateTime;
  updatedAt: UtcDateTime;
}

export interface TreeEntry {
  path: string; // 从仓库根目录开始的完整相对路径
  name: string;
  type: string; // 普通目录为 dir,普通文件为 file
  size: number; // 字节
  blobSha: string;
}

export interface Tree {
  commitSha: string;
  path: string; // 根目录为 ""
  entries: TreeEntry[]; // 当前目录的直接子项
}

export interface ProjectFile {
  commitSha: string;
  path: string;
  blobSha: string;
  size: number; // 字节
  encoding: 'utf-8' | 'base64';
  content: string;
  editable: boolean;
}

export interface Commit {
  commitSha: string;
  message: string;
}

export interface HistoryEntry {
  commitSha: string;
  message: string;
  authorName: string;
  authorDate: string; // 仓库服务返回的日期字符串
}

export interface Comment {
  commentCode: string;
  author: PublicUser;
  content: string;
  createdAt: UtcDateTime;
}

项目示例与状态含义

已发布项目的 data 示例:

{
  "projectCode": "22222222222222222222222222222222",
  "name": "机器人示例项目",
  "description": "模型、配置和说明文件",
  "projectType": "GENERAL",
  "owner": {
    "userCode": "11111111111111111111111111111111",
    "nickname": "用户_11111111"
  },
  "repoStatus": "READY",
  "publishStatus": "PUBLISHED",
  "publishedCommitSha": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "publishedAt": "2026-10-13T08:30:00",
  "sourceProjectCode": null,
  "sourceCommitSha": null,
  "likeCount": 3,
  "commentCount": 2,
  "liked": false,
  "createdAt": "2026-10-13T08:00:00",
  "updatedAt": "2026-10-13T08:30:00"
}
状态或字段 前端使用方式
repoStatus = CREATING 仓库初始化未完成,可能需要人工核对;关闭文件读取、提交和发布入口
repoStatus = READY 仓库已就绪,可进入文件操作;仍需处理版本冲突或写入待核对错误
repoStatus = FAILED 初始化失败,显示失败状态;仍可修改项目信息或删除项目
publishStatus = UNPUBLISHED 当前不在社区展示;这是私有项目状态,不是草稿
publishStatus = PUBLISHED 当前在社区展示
publishedCommitSha / publishedAt 撤回后可能仍保留上一次发布值,是否公开必须判断 publishStatus
sourceProjectCode / sourceCommitSha Fork 来源及复制的源版本;普通新项目为 null
liked 当前请求用户是否点赞,匿名访问为 false

工作区归属由 owner.userCode 判断,不存在 workspaceCode。updatedAt 不代表仓库最新提交时间。来源项目撤回或删除后,sourceProjectCode 仍可能存在,访问该来源的社区详情会返回 404。

登录和用户

获取图片验证码

GET /api/auth/captcha,无需登录,无参数。

data 示例中 image 仅展示格式前缀,实际值为完整图片:

{
  "captchaCode": "55555555555555555555555555555555",
  "image": "data:image/png;base64,...",
  "expiresIn": 120
}

将 image 作为图片 src,将 captchaCode 与用户输入答案一起提交。有效期默认 120 秒,以接口返回值为准。验证码只使用一次,答案错误也会消耗验证码;失败后重新获取图片。答案校验忽略首尾空格和大小写。

邮箱登录

POST /api/auth/login,无需登录。

请求字段 必填 约束
email 是 合法邮箱,最多 254 字符,前端提交前去掉首尾空格
captchaCode 是 验证码接口返回的标识
captchaAnswer 是 用户输入的图片验证码

请求:

{
  "email": "user@example.com",
  "captchaCode": "55555555555555555555555555555555",
  "captchaAnswer": "ABCDE"
}

响应示例:

{
  "code": "OK",
  "message": "成功",
  "data": {
    "token": "example-platform-token",
    "tokenType": "Bearer",
    "expiresIn": 86400,
    "user": {
      "userCode": "11111111111111111111111111111111",
      "nickname": "用户_11111111",
      "email": "user@example.com"
    }
  },
  "requestId": "44444444444444444444444444444444"
}

首次登录自动创建用户,邮箱统一转成小写。当前只验证邮箱格式与图片验证码,不发送邮件、不使用密码,也不验证邮箱归属。Token 有效期默认 24 小时,以 expiresIn 为准,不是 JWT,没有刷新 Token 接口;服务重启后需要重新登录。

当前用户和退出登录

GET /api/users/me,需要登录,data 为 User;只有本人用户接口和登录响应包含邮箱,公开作者信息不包含邮箱。

POST /api/auth/logout,需要登录,无请求体,成功 data 为 null。前端清除本地登录状态。已失效 Token 调用退出接口会返回 401,同样可以清除本地登录状态。

类型与项目列表

可选项目类型

GET /api/project-types,无需登录,无参数,data 为 ProjectType[]:

[
  { "code": "GENERAL", "name": "通用" },
  { "code": "HUMANOID", "name": "人形" },
  { "code": "QUADRUPED", "name": "四足" },
  { "code": "WHEELED", "name": "轮式" }
]

左侧类型导航和创建项目下拉框使用这个接口,不在前端写死类型码。“全部”筛选不传 type。当前内置 GENERAL(通用)、HUMANOID(人形)、QUADRUPED(四足)、WHEELED(轮式),创建或修改项目时通过 projectType 提交对应 code,列表筛选时通过 type 提交对应 code。

我的项目列表和社区项目列表

  • GET /api/workspace/projects:需要登录,返回本人所有未删除项目,包括 CREATING、FAILED 项目。
  • GET /api/community/projects:可选登录,仅返回 READY 且 PUBLISHED 的项目。

两者查询参数相同:

参数 必填 默认 说明
page 否 1 页码
size 否 20 每页数量
type 否 无 项目类型 code;注意查询字段叫 type,不是 projectType
keyword 否 无 名称或描述的模糊查询,最多 200 字符;空白值不筛选

请求示例:GET /api/community/projects?page=1&size=20&type=GENERAL&keyword=机器人。使用 URLSearchParams 编码中文等查询值。

成功 data 为 PageResult<Project>。工作区按创建时间倒序,社区按最近发布时间倒序;不支持客户端指定排序。更换类型或关键词时,把 page 重置为 1。

我的项目管理

以下接口需要登录,且只能操作当前用户的项目。项目不存在、已删除或属于其他用户,均返回 404。

创建项目

POST /api/workspace/projects。

请求字段 必填 约束
name 是 非空,最多 100 字符,保存时去掉首尾空格
description 否 最多 2000 字符,省略或 null 时保存为空字符串
projectType 是 类型接口返回的 code,必须精确匹配,最多 64 字符
{
  "name": "机器人示例项目",
  "description": "模型、配置和说明文件",
  "projectType": "GENERAL"
}

成功 data 为 Project,状态为 READY、UNPUBLISHED。后端已创建私有仓库、main 分支和 README.md。使用返回的 projectCode 进入工作区详情,然后读取根目录获取当前 commitSha。

创建是同步请求,没有任务编号、202 响应或操作进度查询接口。请求失败可能已经留下项目记录;先查看错误 data.projectCode 和工作区列表,不要自动重发创建请求。

项目详情

GET /api/workspace/projects/{projectCode},无额外参数,data 为 Project。

修改项目信息

PATCH /api/workspace/projects/{projectCode}。请求字段与创建项目相同,data 为更新后的 Project。

虽然方法为 PATCH,当前接口要求同时提交 name、projectType;description 省略或 null 会清空描述。前端编辑表单应提交完整的三个字段。

已发布项目的名称、描述、类型会直接更新社区展示,不生成文件 Commit。

删除项目

DELETE /api/workspace/projects/{projectCode},无请求体,成功 data 为 null。

项目逻辑删除并从社区撤回,已有独立 Fork 不受影响。再次操作已删除项目返回 404。

目录和文件读取

工作区目录

GET /api/workspace/projects/{projectCode}/tree,需要登录。

参数 必填 说明
path 否 目录相对路径,省略或空字符串表示根目录
commitSha 否 省略时读取当前 main;传入时读取该项目指定提交

data 示例:

{
  "commitSha": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "path": "",
  "entries": [
    {
      "path": "models",
      "name": "models",
      "type": "dir",
      "size": 0,
      "blobSha": "cccccccccccccccccccccccccccccccccccccccc"
    },
    {
      "path": "README.md",
      "name": "README.md",
      "type": "file",
      "size": 5,
      "blobSha": "dddddddddddddddddddddddddddddddddddddddd"
    }
  ]
}

entries 仅包含当前目录的直接子项,目录在前,名称升序。展开子目录时传条目的完整 path。需要一致的历史文件视图时,目录和文件读取都使用同一个 commitSha。

工作区文件

GET /api/workspace/projects/{projectCode}/files,需要登录。

参数 必填 默认 说明
path 是 无 普通文件的相对路径
commitSha 否 当前 main 指定历史提交
download 否 false true 返回文件附件

文本文件 data 示例:

{
  "commitSha": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "path": "README.md",
  "blobSha": "dddddddddddddddddddddddddddddddddddddddd",
  "size": 5,
  "encoding": "utf-8",
  "content": "hello",
  "editable": true
}

二进制文件 data 示例:

{
  "commitSha": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "path": "models/data.bin",
  "blobSha": "eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
  "size": 3,
  "encoding": "base64",
  "content": "AAEC",
  "editable": false
}

只有 UTF-8、没有 NUL 字节且不超过文本编辑限制的文件返回 editable=true。二进制文件或超过编辑限制的文本返回 base64,不能直接把 base64 放进编辑器提交;使用上传替换。文件和下载均受单文件读取上限限制。

download=true 成功返回 application/octet-stream,带 Content-Disposition: attachment,不套 JSON。工作区下载需要带 Bearer Token,应使用 fetch 获取 Blob,直接使用 a 标签或 window.open 无法附加该请求头。失败时按 JSON 错误响应处理。

社区目录和文件

  • GET /api/community/projects/{projectCode}/tree:path 用法与工作区一致,data 为 Tree。
  • GET /api/community/projects/{projectCode}/files:支持 path、download,返回与工作区相同的文件数据或二进制。

均可匿名访问,固定读取当前 publishedCommitSha。不要传 commitSha 参数,即使传空字符串也会返回 400。 社区页面只读,需要编辑时先 Fork 到自己的工作区。撤回、删除或未发布项目返回 404。

路径限制

文件和非根目录路径必须为相对路径,最长 1024 字符。支持中文、空格和多级目录,例如 models/轮式机器人/底盘.stl;不加开头或结尾斜杠。根目录在目录接口和上传 directory 中用空字符串。

禁止绝对路径、反斜杠、空路径段、.、..、.git 路径段、冒号及控制字符。读取普通文件接口不支持符号链接或 Git 子模块。使用 URLSearchParams 处理查询编码,不自行拼接未编码的 path。

文件编辑与上传提交

多文件提交

POST /api/workspace/projects/{projectCode}/commits,需要登录。

请求字段 必填 约束
expectedCommitSha 是 当前编辑所基于的完整工作区 SHA
message 是 非空,最多 1000 字符
changes 是 1~500 个文件变更

每个 changes 元素使用以下字段:

字段 说明
action CREATE_FILE、UPDATE_FILE、DELETE_FILE、CREATE_DIRECTORY
path 文件或新目录的相对路径
content CREATE_FILE、UPDATE_FILE 必填,UTF-8 文本;可为 "" 创建或替换为空文件

请求示例中的路径必须符合仓库实际情况:创建路径应尚不存在,修改或删除目标必须存在。

{
  "expectedCommitSha": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "message": "更新说明并添加文件",
  "changes": [
    { "action": "UPDATE_FILE", "path": "README.md", "content": "新的说明" },
    { "action": "CREATE_FILE", "path": "src/main.txt", "content": "hello" },
    { "action": "CREATE_DIRECTORY", "path": "models" },
    { "action": "DELETE_FILE", "path": "old.txt" }
  ]
}

成功 data 为 Commit:

{
  "commitSha": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
  "message": "更新说明并添加文件"
}

一次请求生成一个 Commit。保存成功后,更新编辑器基准 SHA 并重新加载目录和受影响的文件。编辑器输入只存在于当前前端状态中,后端没有自动保存或草稿接口。

新建空目录实际创建 {path}/.gitkeep,目录和文件会在提交时进入仓库。一批不能重复操作同一路径,包含新目录转换成 .gitkeep 后的实际路径。DELETE_FILE、CREATE_DIRECTORY 不需要 content。没有单独的删除目录或重命名接口;删除目录需提交其所有文件的删除操作,包括 .gitkeep,并遵守每批 500 个变更限制。

如果 expectedCommitSha 已不是最新 main,返回 409 CONFLICT。前端保留当前未提交输入,重新读取工作区版本,让用户处理差异后再提交;不要只替换 SHA 后自动覆盖内容。浏览历史版本时应使用只读模式,回到最新版本后再编辑。

上传并提交

POST /api/workspace/projects/{projectCode}/uploads/commit,需要登录,使用 FormData。

multipart 字段 必填 说明
expectedCommitSha 是 基于的当前工作区版本
message 是 非空,最多 1000 字符
directory 否 目标目录,省略或空字符串表示根目录
files 是 重复使用同名 files 字段,1~500 个文件
paths 否 重复使用同名 paths 字段,与 files 顺序和数量一一对应

不传 paths 时使用各文件的原始文件名;传入时每个值是相对于 directory 的路径。例:directory=models、paths=robot/body.stl,最终路径为 models/robot/body.stl,不要重复添加 directory 前缀。

同名文件会替换,界面应说明覆盖行为。所有文件生成一个 Commit,成功 data 与文本提交相同。上传用于二进制文件和较大文本文件的新增或替换。

默认大小限制

限制 数值
在线创建或编辑的单个文本内容 1 MiB,1048576 字节
上传或读取的单文件 10 MiB,10485760 字节
本次上传文件或提交内容总量 50 MiB,52428800 字节
multipart 整个请求 52 MiB,包含传输开销
单批变更或上传文件数量 500

大小按字节计算,文本使用 UTF-8 编码长度,不使用 JavaScript 字符串 length 计算文件体积。以上是当前默认配置,超限返回 413。后端调整业务上传大小时还需同步调整 multipart 配置。

提交历史

GET /api/workspace/projects/{projectCode}/commits?page=1&size=20,需要登录。

data 为 PageResult<HistoryEntry>,只读取 main 的历史,不提供分支切换。历史条目示例:

{
  "commitSha": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
  "message": "更新说明并添加文件",
  "authorName": "用户_11111111",
  "authorDate": "2026-10-13T08:40:00Z"
}

点击历史条目,把 commitSha 传给工作区 tree、files 接口。历史 total 依赖仓库服务的统计响应头,未提供时退化为本页条数;前端也可结合本页 items 数量提供下一页操作。

社区发布和撤回

首次发布和更新社区版本

PUT /api/workspace/projects/{projectCode}/publication,需要登录。

请求:

{
  "commitSha": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
}

commitSha 必须为当前 main 的完整 SHA,不能发布历史提交。成功 data 为 Project,publishStatus=PUBLISHED,publishedCommitSha 为提交的版本,publishedAt 更新为本次发布时间。

同一路径用于首次发布和以后手动更新社区版本。发布后继续提交、上传或创建目录,都不会自动更新社区代码。需要更新时,取得最新工作区 SHA,再调用此接口。项目名称、描述和类型的修改直接更新展示。

例:发布版本 A 后,在工作区提交得到 B,工作区展示 B,社区仍展示 A;再次用 B 调用 publication 后,社区才展示 B。前端可比较工作区 tree.commitSha 与项目 publishedCommitSha,显示“有未发布的更新”。

工作区 SHA 已变化时返回 409 CONFLICT,刷新版本后由用户重新确认发布。成功后刷新工作区详情和社区列表或详情。

撤回社区

DELETE /api/workspace/projects/{projectCode}/publication,需要登录,无请求体,成功 data 为 null。

撤回后项目留在工作区,社区列表、详情、目录、文件、评论列表及新增互动不可访问。原有评论、点赞和发布记录保留,再次发布继续使用;已有独立 Fork 不受影响。

社区详情和 Fork

项目详情

GET /api/community/projects/{projectCode},可选登录,data 为 Project。

列表项点击后用 projectCode 进入前端详情路由,再请求本接口。可并行请求根目录和评论列表。需要当前用户的点赞状态时携带有效 Token。前端页面 URL 由前端定义,后端不返回可直接跳转的页面地址。

Fork 到我的工作区

POST /api/community/projects/{projectCode}/forks,需要登录。

请求字段 必填 说明
name 是 新项目名称,非空,最多 100 字符
publishedCommitSha 是 当前社区详情返回的完整发布版本
{
  "name": "我的机器人副本",
  "publishedCommitSha": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}

成功 data 为当前用户的新 Project,状态 READY、UNPUBLISHED;使用返回的新 projectCode 跳转工作区。类型和描述继承源项目,sourceProjectCode、sourceCommitSha 记录来源。

Fork 复制发布版本的所有普通文件,不复制源仓库提交历史,不自动同步上游。允许同一用户多次 Fork。所有文件复制完成才返回 READY;不支持符号链接或子模块。

源项目发布版本已变化时返回 409 CONFLICT,刷新社区详情后由用户重新确认。Fork 是同步请求,可能耗时较长;提交期间显示加载状态并防止重复点击。超时、网络断开或失败后先查询工作区,不要自动重发。

评论和点赞

评论列表

GET /api/community/projects/{projectCode}/comments?page=1&size=20,可选登录。

data 为 PageResult<Comment>,按创建时间倒序,平铺展示,不提供回复层级。评论 data 示例:

{
  "commentCode": "33333333333333333333333333333333",
  "author": {
    "userCode": "11111111111111111111111111111111",
    "nickname": "用户_11111111"
  },
  "content": "这个项目的结构很清楚",
  "createdAt": "2026-10-13T08:45:00"
}

新增评论

POST /api/community/projects/{projectCode}/comments,需要登录。

{
  "content": "这个项目的结构很清楚"
}

content 非空,最多 2000 字符,保存时去掉首尾空格。成功 data 为新 Comment。只支持纯文本,没有富文本、评论编辑或回复接口;前端以文本渲染。提交成功后刷新评论列表和项目 commentCount,不要自动重试新增评论请求。

删除自己的评论

DELETE /api/comments/{commentCode},需要登录,无请求体,成功 data 为 null。

比较 comment.author.userCode === currentUser.userCode 决定是否显示删除入口,后端仍会校验作者身份。删除他人的、已删除的或不存在的评论返回 404。删除成功后刷新评论列表和项目统计。

点赞和取消点赞

  • PUT /api/community/projects/{projectCode}/like:需要登录,点赞。
  • DELETE /api/community/projects/{projectCode}/like:需要登录,取消点赞。

均无请求体,成功 data 为 null,两者幂等。点赞接口不返回最新计数,成功后重新请求社区详情获取 liked、likeCount;可以先做乐观更新,失败时恢复并刷新详情。

错误码与前端处理

错误响应示例

版本冲突通常不带 data:

{
  "code": "CONFLICT",
  "message": "工作区版本已变化,请刷新后重新提交",
  "data": null,
  "requestId": "44444444444444444444444444444444"
}

部分创建、Fork 或仓库调用错误携带关联项目:

{
  "code": "REMOTE_RESULT_UNKNOWN",
  "message": "仓库连接异常或超时,写入结果需核对",
  "data": {
    "projectCode": "22222222222222222222222222222222"
  },
  "requestId": "44444444444444444444444444444444"
}

错误处理对照

HTTP code 前端处理
400 BAD_REQUEST 参数、分页、类型、路径、SHA 或文件操作不合法,展示 message 并检查请求
400 CAPTCHA_INVALID 验证码错误、已使用或过期,刷新验证码
401 UNAUTHORIZED 清除登录状态,受保护页面进入登录流程;公开 GET 可移除失效 Token 后重新读取
403 ACCOUNT_DISABLED 登录账号不可用,停止登录流程并展示提示
403 FORBIDDEN 无权访问,展示权限提示
404 NOT_FOUND 项目不可访问、目标文件或版本不存在;停止加载目标资源并展示不可用状态
405 METHOD_NOT_ALLOWED 检查请求方法
409 CONFLICT 工作区或发布版本变化,或仓库未就绪,按 message 刷新版本或核对状态
409 GITEA_CONFLICT 仓库内容冲突,刷新目录和文件后由用户处理
409 REMOTE_RESULT_UNKNOWN 上一次仓库写入结果待核对,暂不能继续该项目的仓库写入
413 FILE_TOO_LARGE 文件读取、编辑或上传内容超限,提示大小限制
413 UPLOAD_TOO_LARGE 整体 multipart 请求超限
415 UNSUPPORTED_MEDIA_TYPE 检查 Content-Type,JSON 与 FormData 不要混用
500 CAPTCHA_ERROR 验证码生成失败,可重新获取并记录 requestId
500 PROJECT_INITIALIZATION_ERROR 项目初始化或回写未完成,查看 data.projectCode 和工作区,请后端核对
500 INTERNAL_ERROR 展示服务异常并保留 requestId
502 GITEA_ERROR 仓库服务异常;写请求先核对结果,避免自动重试
502 GITEA_INVALID_RESPONSE 仓库响应无法确认;写请求先核对结果,避免自动重试
503 GITEA_NOT_CONFIGURED 后端缺少仓库配置,请后端处理
504 REMOTE_RESULT_UNKNOWN 仓库连接异常或超时;读请求可重新读取,写请求需先核对结果

通过 HTTP 状态和 code 判断行为,保留 requestId 供排查。通用请求封装不要自动重试创建项目、Fork、评论或文件写入。浏览器超时、取消请求、连接中断不保证后端没有执行成功。

写入结果待核对时,同一进程内会阻止该项目后续仓库写入或发布;仍可读取可用文件、修改项目信息、撤回和删除。CREATING 项目因仓库尚未 READY,不能读取文件。没有 repository_operation 查询接口、自动恢复接口或跨重启完整幂等保证。

页面调用顺序

页面或操作 调用顺序
社区首页 project-types → community/projects;选类型和关键词时重置页码
社区详情 community 项目详情、根目录、评论列表;展开目录或点击文件再读取对应内容
登录页 captcha → login;失败后刷新验证码;成功后保存平台登录状态
我的工作区 users/me → workspace/projects,分别显示仓库状态和发布状态
创建项目 POST workspace/projects → 使用返回 projectCode 进入详情 → tree 获取当前版本
文件编辑 workspace 详情与 tree → files → 判断 editable → commits → 刷新版本、目录和文件
上传文件 tree 获取基准 SHA → uploads/commit → 刷新目录和当前版本
发布或更新社区 获取最新工作区 SHA → publication → 刷新项目和社区页面
Fork 获取社区详情中的发布 SHA → forks → 使用新 projectCode 进入工作区
评论或点赞 完成写请求 → 刷新评论或项目详情中的统计字段

前端请求示例

以下示例使用浏览器 fetch 和 TypeScript,类型声明见前面的响应结构。API_BASE 使用 /api,配合同域反向代理或开发代理。

JSON 与 FormData 请求封装

const API_BASE = '/api';

class ApiError extends Error {
  constructor(
    readonly status: number,
    readonly code: string,
    message: string,
    readonly requestId: string | null,
    readonly data: unknown = null,
  ) {
    super(message);
    this.name = 'ApiError';
  }
}

async function request<T>(
  path: string,
  options: {
    method?: string;
    token?: string;
    body?: unknown;
    signal?: AbortSignal;
  } = {},
): Promise<T> {
  const headers = new Headers({ Accept: 'application/json' });
  if (options.token) headers.set('Authorization', `Bearer ${options.token}`);

  let body: BodyInit | undefined;
  if (options.body instanceof FormData) {
    body = options.body; // 浏览器自动设置 multipart boundary
  } else if (options.body !== undefined) {
    headers.set('Content-Type', 'application/json');
    body = JSON.stringify(options.body);
  }

  const response = await fetch(`${API_BASE}${path}`, {
    method: options.method ?? 'GET',
    headers,
    body,
    signal: options.signal,
  });

  let result: ApiResponse<T>;
  try {
    result = await response.json();
  } catch {
    throw new ApiError(
      response.status,
      'BAD_RESPONSE', // 前端封装错误码,不是后端业务错误码
      '接口未返回有效 JSON',
      response.headers.get('X-Request-Id'),
    );
  }
  if (!response.ok || result.code !== 'OK') {
    throw new ApiError(
      response.status, result.code, result.message,
      result.requestId ?? response.headers.get('X-Request-Id'), result.data,
    );
  }
  return result.data as T; // 返回 null 的接口使用 request<null>
}

调用处捕获 ApiError,按照错误码表处理。fetch 的网络错误和 AbortError 也需要处理;对于写请求,这些错误同样先核对结果。此封装不自动重试,也不用于下载二进制。

列表和文件读取

async function loadProjects(type: string | undefined, keyword: string) {
  const query = new URLSearchParams({ page: '1', size: '20' });
  if (type) query.set('type', type);
  if (keyword.trim()) query.set('keyword', keyword.trim());
  return request<PageResult<Project>>(`/community/projects?${query}`);
}

async function readWorkspaceFile(projectCode: string, path: string, token: string) {
  const query = new URLSearchParams({ path });
  return request<ProjectFile>(
    `/workspace/projects/${encodeURIComponent(projectCode)}/files?${query}`,
    { token },
  );
}

需要 liked 状态时,列表请求也传入有效 token。

上传示例

async function uploadFiles(
  projectCode: string,
  expectedCommitSha: string,
  files: File[],
  token: string,
) {
  const form = new FormData();
  form.append('expectedCommitSha', expectedCommitSha);
  form.append('message', '上传模型文件');
  form.append('directory', 'models');
  for (const file of files) {
    form.append('files', file, file.name);
    form.append('paths', file.name); // 也可改为相对于 models 的多级路径
  }
  return request<Commit>(
    `/workspace/projects/${encodeURIComponent(projectCode)}/uploads/commit`,
    { method: 'POST', token, body: form },
  );
}

工作区下载示例

async function downloadWorkspaceFile(projectCode: string, path: string, token: string) {
  const query = new URLSearchParams({ path, download: 'true' });
  const response = await fetch(
    `${API_BASE}/workspace/projects/${encodeURIComponent(projectCode)}/files?${query}`,
    { headers: { Authorization: `Bearer ${token}` } },
  );
  if (!response.ok) {
    const result = await response.json();
    throw new ApiError(
      response.status, result.code, result.message,
      result.requestId ?? response.headers.get('X-Request-Id'), result.data,
    );
  }
  const objectUrl = URL.createObjectURL(await response.blob());
  const link = document.createElement('a');
  link.href = objectUrl;
  link.download = path.split('/').pop() || 'download';
  document.body.appendChild(link);
  link.click();
  link.remove();
  setTimeout(() => URL.revokeObjectURL(objectUrl), 0);
}

UTC 时间解析

只对项目、评论中不带时区的 UTC 字段使用这个函数;历史 authorDate 已带时区时按其原值解析。

function parseUtcTime(value: UtcDateTime): Date {
  const hasTimezone = /(?:Z|[+-]\d{2}:\d{2})$/i.test(value);
  return new Date(hasTimezone ? value : `${value}Z`);
}

开发代理示例

使用 Vite 时可在现有配置中加入以下 server 配置,保留 /api 路径,不进行 rewrite:

export default {
  server: {
    proxy: {
      '/api': {
        target: 'http://localhost:8993',
        changeOrigin: true,
      },
    },
  },
};

后端人工核对

本节供前端遇到写入结果不明时与后端协作使用。记录 projectCode、requestId、接口路径及操作时间,提供给后端;不要在日志或工单中记录 Token、验证码答案、邮箱或文件内容。

后端先按 projectCode 对应的固定仓库名核对仓库、文件与提交历史。初始化未完成的项目核对后修正 repo_status 和仓库映射;确认没有远端写入仍在执行后,再重启后端解除本机待核对标记。超时不能直接视为未提交后再次写入。数据库结构见 四表数据库说明。