RESTful API

RESTful API（Representational State Transfer API）是一种基于REST架构风格的应用程序接口设计方法，广泛用于Web服务和系统之间的数据交换。REST由Roy Fielding在2000年的博士论文中首次提出，强调无状态性、客户端-服务器分离、统一接口、可缓存性等原则。RESTful API的核心是通过HTTP协议进行资源的创建、读取、更新和删除操作（CRUD）。

RESTful API 的特点

• 无状态性：每个请求都包含了所有必要的信息（如身份验证信息），服务器不会在请求之间保留客户端的状态。
• 客户端-服务器架构：客户端负责用户界面和用户体验，服务器负责数据存储和业务逻辑，二者相互独立。
• 统一接口：RESTful API使用标准的HTTP动词（GET、POST、PUT、DELETE等）进行操作，接口设计规范一致，易于理解和使用。
• 可缓存性：响应数据可以被标记为可缓存，以提高性能和减少服务器负载。
• 分层系统：通过中间层（如负载均衡器、代理服务器）提升系统的可伸缩性和安全性。
• 按需编码：服务器可以将代码或脚本发送到客户端执行，以增强客户端功能。

HTTP动词

• GET：用于读取资源，不会对服务器上的资源造成任何影响。
• POST：用于创建新资源或提交数据，服务器处理请求后创建新资源。
• PUT：用于更新现有资源，将客户端提供的数据覆盖服务器上的资源。
• DELETE：用于删除服务器上的资源。
• PATCH：用于部分更新资源，改变资源的部分内容。

URL设计

RESTful API使用统一资源标识符（URI）来表示资源，每个资源有一个唯一的URL。资源之间的关系通过URL层级表示。

示例URL设计：

• GET /books：获取所有图书列表。
• GET /books/{id}：获取特定ID的图书。
• POST /books：创建新图书。
• PUT /books/{id}：更新特定ID的图书。
• DELETE /books/{id}：删除特定ID的图书。

响应状态码

RESTful API使用HTTP状态码来表示请求的处理结果：

• 200 OK：请求成功，返回数据。
• 201 Created：资源创建成功。
• 204 No Content：请求成功，无返回内容。
• 400 Bad Request：请求无效或格式错误。
• 401 Unauthorized：请求未经授权。
• 404 Not Found：请求的资源不存在。
• 500 Internal Server Error：服务器内部错误。

示例

以下是一个简单的RESTful API示例，使用Node.js和Express框架创建一个书籍管理系统。

服务器代码（Node.js + Express）

复制const express = require("express");
const app = express();
app.use(express.json());

let books = [
 { id: 1, title: "1984", author: "George Orwell" },
 { id: 2, title: "To Kill a Mockingbird", author: "Harper Lee" },
];

// 获取所有书籍
app.get("/books", (req, res) => {
 res.json(books);
});

// 获取特定书籍
app.get("/books/:id", (req, res) => {
 const book = books.find((b) => b.id === parseInt(req.params.id));
 if (!book) return res.status(404).send("Book not found");
 res.json(book);
});

// 创建新书籍
app.post("/books", (req, res) => {
 const book = {
 id: books.length + 1,
 title: req.body.title,
 author: req.body.author,
 };
 books.push(book);
 res.status(201).json(book);
});

// 更新书籍
app.put("/books/:id", (req, res) => {
 const book = books.find((b) => b.id === parseInt(req.params.id));
 if (!book) return res.status(404).send("Book not found");
 book.title = req.body.title;
 book.author = req.body.author;
 res.json(book);
});

// 删除书籍
app.delete("/books/:id", (req, res) => {
 const book = books.find((b) => b.id === parseInt(req.params.id));
 if (!book) return res.status(404).send("Book not found");
 const index = books.indexOf(book);
 books.splice(index, 1);
 res.status(204).send();
});

const port = process.env.PORT || 3000;
app.listen(port, () => console.log(`Listening on port ${port}...`));

总结

RESTful API是一种简单、灵活、易于扩展的Web服务设计方法，通过标准的HTTP协议和动词进行操作，使得客户端和服务器之间的通信更加直观和高效。它适用于各种规模的Web应用程序，从小型项目到大型分布式系统。

Clash 的 External Controller

Clash for Windows 内置了一个 RESTful 风格的控制接口，称为 External Controller。开启后可以通过 HTTP 请求做这些事：

这也是第三方仪表盘、托盘小工具能够实现的基础。

开启与调用

在客户端的 主页 或 配置 页面可以找到 External Controller 的开关与监听地址，形如 127.0.0.1:9090。开启后用任意 HTTP 客户端即可调用：

复制curl http://127.0.0.1:9090/version

# 查询所有代理组
curl http://127.0.0.1:9090/proxies

安全注意事项

这是使用控制接口时最需要留意的部分：

• 默认监听地址决定暴露范围 —— 监听 127.0.0.1 只对本机开放；若改成 0.0.0.0，局域网内任何设备都能调用
• 控制接口本身没有强制认证 —— 谁连得上谁就能操作，包括切换节点与读取流量数据
• 不要直接暴露到公网 —— 一旦映射到公网，等于把本机代理的控制权交出去

由于 Clash for Windows 已经停止维护，新发现的安全问题不会有官方修复。用不到控制接口时，建议直接关闭。

实用场景举例

• 自动化切换 —— 写脚本按延迟自动选择节点
• 流量监控 —— 定期拉取统计，记录每日用量
• 快捷控制 —— 用托盘工具一键切换模式，免得每次开主界面

如果你的使用场景比较简单，直接在客户端界面操作即可，不必启用控制接口。更多相关说明见常见问题。