一、API 是什么？

API（Application Programming Interface，应用程序编程接口） 是不同软件之间沟通的桥梁。
在 Web 开发中，我们常说的 API 通常指 Web API——通过 HTTP 协议提供数据服务，让前端（网页、App）能从服务器获取或提交数据。

举个例子：我的消消乐游戏需要保存玩家分数并展示排行榜，游戏前端不能直接读写服务器文件，于是需要一个 中间人 来接收请求、处理数据、返回结果——这个中间人就是 API。

二、自建 API 的核心原理

2.1 客户端 – 服务器 模型

• 客户端（浏览器、小程序、App）发送 HTTP 请求。

• 服务器（你的 PHP/Node.js/Java 程序）接收请求，执行逻辑，返回 HTTP 响应。

2.2 请求方法（HTTP Methods）

2.3 数据交换格式（JSON）

目前最流行的是 JSON（JavaScript Object Notation），轻量、易读、跨语言。
API 接收请求体（body）中的 JSON，处理后也返回 JSON 给客户端。

2.4 无状态性

每个请求都应包含所有必要信息（如用户身份、操作参数），服务器不保留客户端状态。这使系统易于扩展。

三、自建 API 的完整流程

3.1 规划阶段

• 明确需求：你的 API 要做什么？（例如：获取/提交排行榜数据）

• 设计端点（Endpoint）：确定 URL 路径和对应功能
  比如：

  • GET /api/ranking → 获取排行榜

  • POST /api/ranking → 提交分数

• 定义请求/响应格式：需要哪些字段？返回什么结构？

3.2 技术选型

对于初学者，PHP 是最容易上手的选择，无需复杂环境，上传文件即生效。

3.3 开发实现

以我们的消消乐 API 为例，核心步骤：

1. 接收请求

   • 判断 $_SERVER['REQUEST_METHOD'] 是 GET 还是 POST。

2. 处理请求

   • GET：读取 data.json，返回排行榜。

   • POST：校验参数（name、score），将新记录追加到 data.json，排序并截取前10名。

3. 返回响应

   • 设置 Content-Type: application/json，用 json_encode() 输出。

3.4 数据持久化

没有数据库时，可借助 JSON 文件 存储数据（适合低并发场景）。
注意使用 文件锁（flock） 防止并发写入冲突。

3.5 安全考虑

• 输入校验：防止 XSS、SQL 注入（虽不是SQL，但仍要清洗数据）。

• 跨域（CORS）：允许哪些域名访问你的 API？通过 Access-Control-Allow-Origin 头控制。

• 限流（Rate Limiting）：防止恶意刷接口，记录 IP 和请求时间。

• 身份验证（Authentication）：对于敏感操作（如清空数据），使用 API Key 或 Token。

3.6 部署上线

• 上传代码到服务器（如宝塔面板创建的网站目录）。

• 确保文件权限正确（data.json 可写）。

• 测试端点是否返回预期数据。

四、案例拆解：槐序Lab实验室消消乐排行榜 API

4.1 目录结构

/网站根目录/

├── index.php # API 入口（处理所有请求）

├── data.json # 数据存储

├── api.log # 访问日志

└── .htaccess # 可选，配置跨域（若 Nginx 则无需）

4.2 请求与响应示例

GET 请求

GET /?period=all&page=1&limit=10

响应：

{

“success”: true,

“data”: [

{“name”:”玩家1″,”score”:500,”avatar”:”😎”,”datetime”:”2025-08-31 14:30:12″},

{“name”:”玩家2″,”score”:450,”avatar”:”🐱”,”datetime”:”2025-08-31 13:20:05″}

],

“total”: 2,

“page”: 1,

“pages”: 1

}

POST 请求

POST /

Content-Type: application/json

{“name”:”新玩家”,”score”:600,”avatar”:”🦊”}

响应：

{

“success”: true,

“data”: […],

“isTop10”: true,

“rank”: 1,

“achievement”: {“icon”:”🌟”,”name”:”初出茅庐”,”color”:”#2196F3″}

}

4.3 关键代码片段

读取数据（带锁）：

function readData() {

global $dataFile;

if (!file_exists($dataFile)) return [‘ranking’ => []];

$fp = fopen($dataFile, ‘r’);

flock($fp, LOCK_SH);

$content = stream_get_contents($fp);

flock($fp, LOCK_UN);

fclose($fp);

return json_decode($content, true) ?: [‘ranking’ => []];

}

处理 POST 并写入：

$input = json_decode(file_get_contents(‘php://input’), true);

$name = trim(strip_tags($input[‘name’]));

$score = intval($input[‘score’]);

$data[‘ranking’][] = [‘name’=>$name, ‘score’=>$score, ‘datetime’=>date(‘Y-m-d H:i:s’)];

usort($data[‘ranking’], fn($a,$b) => $b[‘score’] – $a[‘score’]);

writeData($data);

五、最佳实践与建议

1. 版本控制：在 URL 中包含版本号，如 /v1/ranking，便于未来升级。

2. 错误码：使用标准的 HTTP 状态码（200、400、401、403、404、500 等）并附带清晰错误信息。

3. 日志记录：记录每个请求的 IP、时间、方法、状态，方便排查问题。

4. 性能优化：数据量大时改用 Redis 或数据库；对静态数据启用缓存头。

5. 安全性：始终使用 HTTPS；敏感操作加认证；限制请求频率。

六、总结

自建 API 并不神秘，它本质上就是接收请求 → 处理数据 → 返回响应的简单循环。
通过选择合适的工具（如 PHP）、合理设计端点、妥善处理数据安全，你就能快速搭建属于自己的接口服务。

下一步方向：

• 学习使用数据库（MySQL）替代 JSON 存储，支持更高并发。

• 引入 RESTful 规范，让你的 API 更专业。

• 探索 OpenAPI/Swagger，自动生成文档。

如果你已经跟着本文实现了消消乐排行榜 API，恭喜你，已经迈出了 API 开发的第一步！🚀

实战网站例子：消消乐-槐序Lab-槐序实验室