52 lines
2.3 KiB
Markdown
52 lines
2.3 KiB
Markdown
RESTful API（Representational State Transfer 风格的接口）是一种常见的 Web 服务设计规范，其核心思想和特点包括：
|
||
|
||
1. **资源（Resource）为中心**
|
||
- 把系统中的一切“对象”都看作资源，每个资源通过一个唯一的 URI（路径）来标识。
|
||
- 例如：`/models` 可能对应“模型列表”资源，`/models/123` 对应“ID 为 123 的模型”资源。
|
||
|
||
2. **使用 HTTP 方法表示操作**
|
||
- **GET**：读取资源（不应改变服务器状态），
|
||
- **POST**：创建资源，
|
||
- **PUT/PATCH**：更新资源，
|
||
- **DELETE**：删除资源。
|
||
这样可以让接口语义清晰、与 HTTP 协议天然契合。
|
||
|
||
3. **无状态性（Stateless）**
|
||
- 每一次请求都包含完成该请求所需的所有信息，服务端不在请求之间保留客户端状态。
|
||
- 优点是易于扩展与负载均衡；缺点是每次请求都要重复认证/传递上下文。
|
||
|
||
4. **表现层（Representation）**
|
||
- 客户端与服务端通过“表现层”交换资源状态，通常是 JSON、XML 或其他格式。
|
||
- 比如 `GET /models/123` 返回如下 JSON：
|
||
```json
|
||
{
|
||
"id": 123,
|
||
"name": "gpt-4",
|
||
"status": "deployed"
|
||
}
|
||
```
|
||
|
||
5. **超媒体驱动（HATEOAS，可选）**
|
||
- 在响应中带上“链接”（links），告诉客户端可以做哪些后续操作，比如：
|
||
```json
|
||
{
|
||
"id": 123,
|
||
"links": [
|
||
{ "rel": "update", "href": "/models/123", "method": "PUT" },
|
||
{ "rel": "delete", "href": "/models/123", "method": "DELETE" }
|
||
]
|
||
}
|
||
```
|
||
- 这样客户端无须硬编码所有路径，能动态发现可用操作。
|
||
|
||
---
|
||
|
||
### 在 LLMHub 中的应用
|
||
|
||
在我们的 PRD 里，“统一抽象接口层”采用 RESTful API 设计，并以 OpenAPI 3.0 规范来描述，这意味着：
|
||
|
||
- 每个大模型相关的功能（列出模型、部署模型、调用模型）都被定义为一种资源操作；
|
||
- 开发者通过标准的 HTTP 方法和约定好的路径，就能对接各种底层模型平台；
|
||
- 文档会自动生成（Swagger UI），并确保接口清晰、一致且易于测试。
|
||
|
||
这样，无论后端具体集成了哪家大模型服务，上层调用逻辑都保持不变——真正达到了“屏蔽底层差异、统一使用体验”的目标。 |