RESTful API 的设计与实现
原创RESTful API 的设计与实现
原创
在当今的互联网时代，前后端分离已经成为主流，而 RESTful API 作为一种标准化的接口设计方式，被广泛应用于 Web 开发。很多人对 RESTful API 的概念有些模糊，不知道它到底是干嘛的，也不知道怎么设计一个合理的 API。本篇文章就用大白话，把 RESTful API 的核心知识讲清楚，并且带你一步步实现一个 RESTful API。
什么是 RESTful API？
首先，我们拆开来看：
- REST（Representational State Transfer），翻译成中文是“表述性状态转移”，但说实话，这个翻译挺绕口的，没啥直观的感觉。简单理解就是一种基于 HTTP 的数据交互风格，用 URL 代表资源，用 HTTP 方法（GET、POST、PUT、DELETE）来操作这些资源。
- API（Application Programming Interface），就是“应用程序接口”，让不同的程序能互相通信的桥梁。
合起来，RESTful API 就是一种基于 HTTP 设计的接口风格，让前端和后端能清晰、标准地进行数据交互。它强调的是：
- 资源（Resource）：比如用户、文章、商品等数据对象。
- URL 代表资源：每个 URL 对应一个具体的资源，比如
/users/1代表 ID 为 1 的用户。 - HTTP 方法决定操作：
GET /users获取所有用户GET /users/1获取 ID 为 1 的用户POST /users创建新用户PUT /users/1更新 ID 为 1 的用户DELETE /users/1删除 ID 为 1 的用户
这种风格的好处在于直观、清晰、符合 HTTP 规范，前端看到接口文档就知道该怎么调用，不需要写一堆 action=add_user 之类的乱七八糟的参数。
如何设计 RESTful API？
要设计一个合理的 RESTful API，我们需要遵循以下原则：
1. 资源命名要清晰
API 里的 URL 代表的是资源，所以 URL 里应该是名词，而不是动词。例如：
✅ GET /articles 获取所有文章
❌ GET /getArticles 这里的 get 是多余的
✅ POST /users 创建新用户
❌ POST /createUser 这里的 create 也是多余的
因为 HTTP 方法本身已经表达了对资源的操作，所以 URL 里就不要再加 get、create、update 这些动词了。
2. 使用 HTTP 方法表示操作
RESTful API 强调使用标准的 HTTP 方法：
GET读取数据POST创建数据PUT更新数据DELETE删除数据
如果接口是 GET /users，一看就知道是获取用户数据，而 DELETE /users/1，一看就知道是删除 ID 为 1 的用户，完全不需要额外解释，清晰直观。
3. 返回合理的 HTTP 状态码
API 调用成功或者失败，不应该只返回 200 OK，而应该使用合适的状态码：
200 OK：请求成功，比如GET /users201 Created：资源创建成功，比如POST /users204 No Content：删除成功但没有返回数据，比如DELETE /users/1400 Bad Request：请求参数有误，比如POST /users但缺少name字段401 Unauthorized：未授权，比如访问需要登录的接口但没带 Token403 Forbidden：没有权限，比如普通用户想访问管理员页面404 Not Found：资源不存在，比如访问GET /users/9999但 ID 9999 的用户不存在500 Internal Server Error：服务器出错，比如数据库崩了
状态码用得好，前端开发者看到错误码就能知道问题出在哪里，不用瞎猜。
4. 数据返回格式统一
API 返回的数据格式应该统一，通常用 JSON，因为 JSON 结构清晰、体积小、解析快，几乎所有编程语言都支持。比如：
{
"code": 200,
"message": "请求成功",
"data": {
"id": 1,
"name": "张三",
"email": "zhangsan@example.com"
}
}如果接口出错：
{
"code": 400,
"message": "缺少必填字段 name"
}返回格式统一，前端就不用到处写 if (res.status === 200) 这种判断逻辑，直接检查 code 值就行了。
如何实现 RESTful API？
下面，我们用 PHP + MySQL 搭建一个简单的 RESTful API，假设我们要做一个用户管理系统，支持：
- 获取所有用户
- 获取单个用户
- 创建用户
- 更新用户
- 删除用户
1. 创建数据库
CREATE TABLE users (
id INT AUTO_INCREMENT PRIMARY KEY,
name VARCHAR(50) NOT NULL,
email VARCHAR(100) UNIQUE NOT NULL
);2. 连接数据库
<?php
$pdo = new PDO("mysql:host=localhost;dbname=test;charset=utf8", "root", "");
$pdo->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);
?>3. 处理请求
创建 api.php：
<?php
require 'db.php';
$method = $_SERVER['REQUEST_METHOD'];
$uri = explode('/', trim($_SERVER['REQUEST_URI'], '/'));
if ($uri[0] !== 'users') {
http_response_code(404);
echo json_encode(["message" => "Not Found"]);
exit;
}
switch ($method) {
case 'GET':
if (isset($uri[1])) {
getUser($pdo, $uri[1]);
} else {
getAllUsers($pdo);
}
break;
case 'POST':
createUser($pdo);
break;
case 'PUT':
if (isset($uri[1])) {
updateUser($pdo, $uri[1]);
} else {
echo json_encode(["message" => "Missing ID"]);
}
break;
case 'DELETE':
if (isset($uri[1])) {
deleteUser($pdo, $uri[1]);
} else {
echo json_encode(["message" => "Missing ID"]);
}
break;
default:
http_response_code(405);
echo json_encode(["message" => "Method Not Allowed"]);
}
?>4. 定义具体操作
function getAllUsers($pdo) {
$stmt = $pdo->query("SELECT * FROM users");
echo json_encode($stmt->fetchAll(PDO::FETCH_ASSOC));
}
function getUser($pdo, $id) {
$stmt = $pdo->prepare("SELECT * FROM users WHERE id = ?");
$stmt->execute([$id]);
echo json_encode($stmt->fetch(PDO::FETCH_ASSOC));
}
function createUser($pdo) {
$data = json_decode(file_get_contents("php://input"), true);
$stmt = $pdo->prepare("INSERT INTO users (name, email) VALUES (?, ?)");
$stmt->execute([$data['name'], $data['email']]);
echo json_encode(["message" => "User created"]);
}
function updateUser($pdo, $id) {
$data = json_decode(file_get_contents("php://input"), true);
$stmt = $pdo->prepare("UPDATE users SET name = ?, email = ? WHERE id = ?");
$stmt->execute([$data['name'], $data['email'], $id]);
echo json_encode(["message" => "User updated"]);
}
function deleteUser($pdo, $id) {
$stmt = $pdo->prepare("DELETE FROM users WHERE id = ?");
$stmt->execute([$id]);
echo json_encode(["message" => "User deleted"]);
}总结
RESTful API 的核心就是“资源 + HTTP 方法”，只要掌握这个思路，设计 API 就很简单了！
原创声明：本文系作者授权腾讯云开发者社区发表，未经许可，不得转载。
如有侵权，请联系 cloudcommunity@tencent.com 删除。
原创声明：本文系作者授权腾讯云开发者社区发表，未经许可，不得转载。
如有侵权，请联系 cloudcommunity@tencent.com 删除。
腾讯云开发者
