RakuLLApp 的客户端和后端服务主要通过 HTTP API 通信。理解这几个词，才能看懂服务文档里的 GET /api/articles、POST /v1/data/files 等接口表格。

​
从 HTTP 请求说起

HTTP 是客户端与服务端交换消息的一套规则。一次调用由请求和响应组成： 
客户端 -- HTTP 请求 --> 服务端
客户端 <-- HTTP 响应 -- 服务端
请求通常包含：
部分示例用途
Method（方法）GET、POST表达希望执行的操作类型
Path（路径）/api/articles/42定位资源或功能
Headers（请求头）Authorization: Bearer ...携带身份、内容类型等元数据
Body（请求体）{"title":"..."}携带要提交的数据，常用 JSON
响应通常包含状态码、响应头和响应体。JSON 是常见的数据格式，但 HTTP 也可以传输图片、音频和文件。

​
API、路由与端点

API 是一个组件对外提供的调用契约。对 HTTP API 来说：
  • **路由（route）**是服务端代码中对某个方法和路径的匹配规则；
  • **端点（endpoint）**通常指调用方可以访问的“方法 + 路径”；
  • 接口契约还包括请求字段、响应字段、状态码和鉴权要求。
因此 GET /api/articles 和 POST /api/articles 是两个不同端点，即使路径相同。

​
常见 HTTP 方法

方法常见含义示例
GET读取，不应修改资源获取文章列表
POST创建资源或触发操作上传文章、创建收藏
PUT整体替换资源替换一份完整配置
PATCH修改资源的一部分修改文章可见性
DELETE删除资源删除收藏夹
这些是约定，不是数据库命令。最终行为以该端点的文档和实现为准。

​
CRUD 是什么

CRUD 是四类基本数据操作的缩写：Create（创建）、Read（读取）、Update（更新）、Delete（删除）。它们常与 HTTP 方法对应：
CRUD常用 HTTP 方法
CreatePOST
ReadGET
UpdatePUT 或 PATCH
DeleteDELETE
“提供收藏夹 CRUD”就是提供收藏夹的创建、查询、修改和删除能力。

​
常见状态码

状态码含义
200 OK请求成功
201 Created资源创建成功
400 Bad Request请求格式或参数有误
401 Unauthorized未登录或凭证无效
403 Forbidden身份有效，但没有权限
404 Not Found资源不存在，或为避免泄露而表现为不存在
500 Internal Server Error服务端发生未处理错误

​
RakuLLApp 中的约定

  • /api/* 是面向客户端的公开接口；
  • /v1/* 主要是服务之间调用的内部接口；
  • 请求和响应大多使用 JSON；
  • 需要登录的端点通过 Authorization: Bearer <jwt> 鉴权；
  • 长任务的持续进度不是普通的一次性响应，而使用 SSE。
调试接口时，先确认方法、完整 URL、请求头、请求体和响应状态码。只看路径通常不足以定位问题。
项目实际接口请从 服务模块 开始阅读。