Slim框架是PHP生态中非常轻量的微框架，它专注于处理HTTP请求和响应，不携带任何多余的组件。对于只需要提供API接口、不需要完整MVC结构的项目来说，Slim比Laravel或Symfony更轻便，启动速度也更快。这篇文章会带你从零开始，用Composer安装Slim 4，创建两个基本的API接口（一个GET查询，一个POST创建），并加入必要的中间件让接口能够被前端跨域调用。整个过程不需要任何数据库连接，所有数据暂时用数组模拟，方便你快速验证路由和响应格式。
环境准备与项目初始化
Slim 4要求PHP 7.2以上版本，推荐使用PHP 7.4或8.x。首先确认你的机器上已经安装了Composer，然后在终端里创建一个新目录，比如slim-api-demo，进入目录后执行下面的命令来引入Slim框架和PSR-7实现。Slim本身不包含HTTP消息实现，需要额外安装slim/psr7这个包，它提供了符合PSR-7标准的Request和Response对象。
composer require slim/slim:4.* slim/psr7
安装完成后，目录下会生成vendor目录和composer.json、composer.lock文件。接下来创建项目的入口文件。按照Slim 4的推荐结构，入口文件放在public/index.php中，这样Web服务器只需要把文档根指向public目录即可。在项目根目录下创建public文件夹，并在其中新建index.php，写入以下基础代码。这段代码引入了自动加载器，创建Slim应用实例，并定义了一个根路由，然后运行应用。
<?php
use Psr\Http\Message\ResponseInterface as Response;
use Psr\Http\Message\ServerRequestInterface as Request;
use Slim\Factory\AppFactory;
require __DIR__ . '/../vendor/autoload.php';
$app = AppFactory::create();
$app->get('/', function (Request $request, Response $response, $args) {
$response->getBody()->write('Hello, Slim API!');
return $response;
});
$app->run();
注意这里使用了AppFactory::create()来创建应用实例，这是Slim 4的标准方式。如果你需要添加依赖注入容器、错误处理中间件等，可以在create()之后进行配置。此时在命令行中切换到public目录，执行php -S localhost:8080启动内置服务器，然后访问http://localhost:8080/就能看到输出。不过为了搭建API接口，我们还需要继续完善路由和JSON响应格式。
注册GET和POST路由并处理JSON数据
API接口最常见的操作就是查询和创建资源。在Slim中注册路由非常简单，使用$app->get()、$app->post()、$app->put()等方法即可。路由回调函数的第三个参数$args包含URL中的占位符，例如/users/{id}中的id。下面我们创建一个/api/users的GET接口，返回一个用户列表，以及一个/api/users的POST接口，接收JSON格式的用户数据并创建新用户。为了简化演示，用户数据保存在一个静态数组里。
<?php
use Psr\Http\Message\ResponseInterface as Response;
use Psr\Http\Message\ServerRequestInterface as Request;
use Slim\Factory\AppFactory;
require __DIR__ . '/../vendor/autoload.php';
$app = AppFactory::create();
// 模拟数据存储
$users = [
['id' => 1, 'name' => 'Alice', 'email' => 'alice@ipipp.com'],
['id' => 2, 'name' => 'Bob', 'email' => 'bob@ipipp.com'],
];
// GET 返回用户列表
$app->get('/api/users', function (Request $request, Response $response) use ($users) {
$payload = json_encode($users, JSON_UNESCAPED_UNICODE);
$response->getBody()->write($payload);
return $response->withHeader('Content-Type', 'application/json');
});
// POST 创建新用户
$app->post('/api/users', function (Request $request, Response $response) use (&$users) {
$body = $request->getBody();
$data = json_decode($body, true);
if (!isset($data['name']) || !isset($data['email'])) {
$error = ['error' => 'name and email are required'];
$response->getBody()->write(json_encode($error));
return $response->withHeader('Content-Type', 'application/json')->withStatus(400);
}
$newUser = [
'id' => count($users) + 1,
'name' => $data['name'],
'email' => $data['email'],
];
$users[] = $newUser;
$response->getBody()->write(json_encode($newUser, JSON_UNESCAPED_UNICODE));
return $response->withHeader('Content-Type', 'application/json')->withStatus(201);
});
$app->run();
上面的代码中，use (&$users)使用了引用传递，这样在闭包内部修改数组可以影响外部变量。实际项目中数据通常来自数据库或缓存，这里只是演示。注意json_encode的第二个参数JSON_UNESCAPED_UNICODE可以避免中文字符被转义成\uXXXX，让返回的JSON更易读。POST接口在请求体缺少name或email时返回400状态码和错误信息，符合RESTful API的语义。
测试这些接口可以使用curl命令。例如在另一个终端里执行curl http://localhost:8080/api/users查看列表，执行curl -X POST http://localhost:8080/api/users -H "Content-Type: application/json" -d '{"name":"Charlie","email":"charlie@ipipp.com"}'来创建用户。如果返回201和新建的用户JSON，说明路由和请求处理正常工作。
添加中间件处理CORS与统一格式
真实的前后端分离项目中，浏览器会发送跨域请求，这时API必须返回正确的CORS响应头，否则前端无法读取数据。Slim使用PSR-15中间件标准，可以在应用级别或路由组级别添加中间件。下面编写一个简单的CORS中间件类，它会在所有响应上添加Access-Control-Allow-Origin等头信息，并处理预检请求（OPTIONS）。创建src/Middleware/CorsMiddleware.php文件，内容如下。
<?php
namespace App\Middleware;
use Psr\Http\Message\ResponseInterface as Response;
use Psr\Http\Message\ServerRequestInterface as Request;
use Psr\Http\Server\MiddlewareInterface;
use Psr\Http\Server\RequestHandlerInterface as Handler;
class CorsMiddleware implements MiddlewareInterface
{
public function process(Request $request, Handler $handler): Response
{
$response = $handler->handle($request);
$response = $response
->withHeader('Access-Control-Allow-Origin', '*')
->withHeader('Access-Control-Allow-Headers', 'Content-Type, Authorization')
->withHeader('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE, OPTIONS');
return $response;
}
}
然后在入口文件中注册这个中间件。Slim提供了$app->add()方法添加全局中间件，注意中间件的添加顺序是从后往前的，即最后添加的会最先执行。同时要处理OPTIONS请求，因为浏览器预检时会发送OPTIONS方法。可以在应用启动前添加一个OPTIONS路由，返回200和CORS头。修改public/index.php如下。
<?php
use App\Middleware\CorsMiddleware;
use Psr\Http\Message\ResponseInterface as Response;
use Psr\Http\Message\ServerRequestInterface as Request;
use Slim\Factory\AppFactory;
require __DIR__ . '/../vendor/autoload.php';
$app = AppFactory::create();
// 注册CORS中间件
$app->add(new CorsMiddleware());
// 处理预检请求
$app->options('/{routes:.+}', function (Request $request, Response $response) {
return $response;
});
// 其余路由保持不变...
$app->get('/api/users', function (Request $request, Response $response) {
// ...
});
$app->run();
除了CORS，API项目通常还需要统一的响应格式和错误处理。Slim 4默认的错误处理中间件会返回HTML格式的异常页面，对于API不够友好。你可以在AppFactory::create()之后关闭默认错误处理，然后添加自定义的错误中间件，将异常转换为JSON格式输出。例如创建一个ErrorHandlerMiddleware，在try/catch中调用下一个处理器，捕获Throwable后返回500和JSON错误信息。这里不再展开完整实现，但思路是在最外层包裹一个中间件，统一处理异常并返回结构化的错误JSON。
项目结构与后续扩展建议
当API接口越来越多时，把所有路由都写在index.php里会变得难以维护。Slim支持路由分组和控制器类。你可以将路由定义拆分成独立的文件，例如app/routes.php，然后在入口文件中require这个文件。对于控制器，可以创建一个UserController类，在路由中使用$app->get('/api/users', [UserController::class, 'index'])的方式调用。这样结构更清晰，也方便进行单元测试。
另外，Slim与依赖注入容器配合得很好。你可以安装php-di/php-di并且使用AppFactory::setContainer()设置容器，这样在路由回调或控制器构造函数中就可以自动注入服务对象。数据库方面，Slim本身没有内置ORM，但你可以选择使用Eloquent、Doctrine或者直接使用PDO，根据自己的习惯来。对于生产环境，建议在入口文件前放置一个index.php并配置Nginx或Apache的URL重写规则，把所有请求转发给这个文件，同时关闭PHP错误显示、开启日志记录。
本文展示的只是一个最小可用的Slim API骨架，实际项目还需要考虑身份验证、输入校验、速率限制等。如果你想深入练习，可以继续为这个示例添加PUT和DELETE路由，或者在POST接口中加入更严格的数据校验逻辑，比如检查邮箱格式是否合法。Slim框架的文档非常清晰，遇到问题可以查阅官方手册中关于路由、中间件和PSR-7的章节。