Apigility是一款基于Zend Framework开发的PHP API构建工具，它可以帮助开发者快速搭建符合RESTful规范的API服务，同时自动生成接口文档、处理请求验证和认证授权等通用逻辑，大幅降低API开发的工作量。
Apigility的核心特性
Apigility的设计目标是让API开发更标准化、更高效，它具备以下核心特性：
- 自动生成符合RESTful规范的接口结构，支持GET、POST、PUT、DELETE等标准HTTP方法
- 内置接口文档生成功能，修改接口配置后文档会自动同步更新
- 支持多种认证方式，包括HTTP基础认证、OAuth2等，无需开发者手动实现认证逻辑
- 提供请求参数验证、响应数据过滤等通用能力，减少重复代码编写
- 支持API版本管理，方便后续接口的迭代升级
PHP环境下安装Apigility
Apigility可以通过Composer进行安装，首先确保本地已经安装了PHP 7.4及以上版本，以及Composer依赖管理工具，执行以下命令完成安装：
# 创建项目目录 mkdir apigility_demo && cd apigility_demo # 通过Composer安装Apigility composer create-project zfcampus/zf-apigility-skeleton # 启动内置开发服务器 php -S 127.0.0.1:8080 -t public
安装完成后访问127.0.0.1:8080，就可以进入Apigility的管理界面，开始配置API服务。
创建第一个API资源
在Apigility管理界面中，我们可以快速创建API资源，以下是手动配置资源的基本步骤，首先需要在配置文件中定义资源相关的参数：
<?php
// config/autoload/rest-api.global.php 中的资源配置示例
return [
'zf-rest' => [
'Demo\V1\Rest\User\UserResource' => [
'service_name' => 'Demo\V1\Rest\User\UserResource',
'entity_class' => 'Demo\V1\Rest\User\UserEntity',
'collection_class' => 'Demo\V1\Rest\User\UserCollection',
'route_name' => 'demo.rest.user',
'route_match' => '/user',
'identifier_name' => 'id',
'collection_name' => 'user',
'resource_http_options' => ['GET', 'POST', 'PUT', 'DELETE'],
],
],
];
接下来需要实现对应的资源类，处理具体的请求逻辑：
<?php
namespace DemoV1RestUser;
use ZFApiProblemApiProblem;
use ZFRestAbstractResourceListener;
class UserResource extends AbstractResourceListener
{
// 处理GET请求，获取用户列表
public function fetchAll($params = [])
{
// 模拟从数据库获取用户数据
$users = [
['id' => 1, 'name' => '张三', 'age' => 25],
['id' => 2, 'name' => '李四', 'age' => 28],
];
return $users;
}
// 处理GET请求，获取单个用户
public function fetch($id)
{
if ($id == 1) {
return ['id' => 1, 'name' => '张三', 'age' => 25];
}
return new ApiProblem(404, '用户不存在');
}
// 处理POST请求，创建新用户
public function create($data)
{
// 模拟创建用户逻辑
return ['id' => 3, 'name' => $data->name, 'age' => $data->age];
}
}
配置API认证规则
Apigility内置了认证配置能力，我们可以在管理界面中直接设置认证规则，也可以手动修改配置文件实现。以下是配置HTTP基础认证的示例：
<?php
// config/autoload/auth.global.php 认证配置示例
return [
'zf-mvc-auth' => [
'authentication' => [
'adapters' => [
'http_basic' => [
'adapter' => 'http_basic',
'options' => [
'realm' => 'api_demo',
'htpasswd' => __DIR__ . '/../htpasswd',
],
],
],
],
'authorization' => [
'Demo\V1\Rest\User\UserResource' => [
'GET' => true, // 允许未认证访问GET请求
'POST' => 'http_basic', // POST请求需要HTTP基础认证
'PUT' => 'http_basic',
'DELETE' => 'http_basic',
],
],
],
];
配置完成后，访问需要认证的接口时，就需要在请求头中携带对应的认证信息，否则会返回401未授权响应。
生成和查看API文档
Apigility会自动根据接口配置生成文档，访问管理界面中的文档入口，就可以看到所有API的详细说明，包括请求地址、请求参数、响应格式、错误码等信息。如果需要导出文档，也可以通过配置生成JSON格式的文档数据，方便对接前端开发人员查看。
Apigility在Zend API开发中的定位
Apigility是Zend生态中专门用于API快速开发的工具，它基于Zend Framework的组件构建，和Zend Framework的应用可以无缝集成。如果项目本身使用Zend Framework开发，使用Apigility搭建API可以复用已有的组件和配置，降低开发成本。对于需要快速输出标准化API的PHP项目，Apigility是一个很实用的选择，它把很多通用的API开发逻辑封装成了可配置的功能，让开发者可以专注于业务逻辑的实现。