PhpBoot 入门（一）快速开发 RESTful 接口

PhpBoot 是一款为快速开发 RESTful API 而设计的 PHP 框架（更多内容请前往 PbpBoot Github）。本文为你演示如何使用 PhpBoot 快速开发一套 RESTful 风格的接口。

关于 RESTful

当前 RESTful 已经不是新鲜的名词了，抛开抽象的定义，我认为一个通俗的解释可以是：按文件系统的方式去设计接口，即把接口提供的功能，当做是对“目录”的“操作”。比如一个登录接口，按 RESTful 设计，可以是POST /tokens/，即把登录，当做新建一个令牌，这里的/tokens/就是“目录”，POST就是对目录的“操作”。关于 RESTful 比较准确的定义，可以看这里。关于 RESTful 最佳实践，可以看这里。

示例接口

下面我将演示如何用 PhpBoot 编写一组“图书管理”接口，这些接口包括：

接口名	METHOD	URI	请求示例	响应示例
查询图书	GET	/books/	GET /books/?name=php&offset=0&limit=1	{ "total": 0, "data": [ { "id": 0, "name": "string", "brief": "string", "pictures": [ "string" ] } ] }
获取图书详情	GET	/books/{id}	GET /books/1	{ "id": 0, "name": "string", "brief": "string", "pictures": [ "string" ] }
新建图书	POST	/books/	POST /books/ { "id": 0, "name": "string", "brief": "string", "pictures": [ "string" ] }	123
删除图书	DELETE	/books/{id}	DELETE /books/1

项目目录结构

app
- Controllers
  - Books.php 接口实现
- Entities
  - Book.php 数据实体定义
config
- config.php 配置
public
- index.php 入口
vendor 依赖包

入口

index.php 作为项目入口，通常只需要指定配置文件和 Controllers 目录的路径即可。最终项目对外提供的接口，由不同的 Controllers 的实现类提供。

<?php
require __DIR__.'/../vendor/autoload.php';

use PhpBoot\Application;

$app = Application::createByDefault(__DIR__.'/../config/config.php');
//扫描 Controllers 目录，自动加载所有路由
$app->loadRoutesFromPath( __DIR__.'/../App/Controllers', 'App\\Controllers');
//执行请求
$app->dispatch();

接口实现

定义 Book 实体

为了在不同接口间共享“图书信息”的数据结构，我们定义一个实体如下：

class Book
{
    /**
     * @var int
     */
    public $id;
    /**
     * 书名
     * @var string
     */
    public $name='';

    /**
     * 简介
     * @var string
     */
    public $brief='';

    /**
     * 图片 url
     * @var string[]
     */
    public $pictures=[];
}

定义 Controller

这里定义了 Books 类作为 Controller，后续接口将实现在此 Books 类中。

/**
 * 提供图书管理接口
 * @path /books/
 */
class Books
{

}

上述代码中的注释@path /books/ 表示 Books 下所有接口，都使用 /books/ 作为前缀。

查询图书接口

/**
 * 查询图书
 *
 * @route GET /
 *
 * @param string $name  查找书名
 * @param int $offset 结果集偏移 {@v min:0}
 * @param int $limit 返回结果最大条数 {@v max:1000}
 * @param int $total 总条数
 * @throws BadRequestHttpException 参数错误
 * @return Book[] 图书列表
 */
public function findBooks($name, &$total, $offset=0, $limit=100)
{
    $total = 1;
    return [new Book()];
}

为便于理解，这段代码只是返回了一组固定的数据，真实场景下应该还会访问数据库或者缓存。下面将说明这段代码的工作方式：

@route 定义了此接口的路由，即 GET /books/(加上了 @path 定义的前缀)。
@param 定义了接口的请求参数和类型，如果不声明@param, 接口参数将从函数定义中提取，如果函数定义中没有申明参数类型，则参数类型被认为是 mixed。
@v 定义了参数的取值范围，若不指定，框架将只会校验请求中的参数类型，即如果参数是类型是 int，则请求中参数必须是可以转换成 int 的类型，如 123 或者"123"等，否则会返回 400 错误
函数的返回值将被 json_encode 后输出到 body。如果函数的参数中没有引用类型（引用类型的参数被认为是输出，而不是输入），return 在 json_encode 后即被当做 body 输出，否则 return 将被赋值给 body 中的 ” data “。

&$total 是引用类型的参数，会被最为输出，默认输出到 body 中同名变量中。如这个接口中，最终输出的 body 形式如下：

{
    "total": 1, //来自 &$total
    "data": [   //来自 return
        {
            "id": 0,
            "name": "string",
            "brief": "string",
            "pictures": [
                "string"
            ]
        }
    ]
}

如果希望将 return 输出到其他位置，或者不使用默认的输入参数绑定方式，可以使用@bind, 比如 @return Book[] 图书列表 {@bind response.content.books} 将使 return 结果绑定在 json 的 "books" 上，而不是默认的 "data"。
$offset=0, $limit=100定义了默认值，如果请求中不包含这些参数，将使用默认值。
注释 @return Book[] 和 @throws BadRequestHttpException 并不会对接口的返回有任何影响，而只会影响文档输出和远程调用（ RPC ）。

获取图书详情接口

/**
 * 获取图书
 * @route GET /{id}
 *
 * @param string $id 指定图书编号
 *
 * @throws NotFoundHttpException 图书不存在
 *
 * @return Book 图书信息
 */
public function getBook($id)
{
    return new Book();
}

路由 @route GET /{id} 指定了 url 的 path 有一个变量{id}，变量的值可以通过函数参数 @id 获取

新建图书

/**
 * 新建图书
 *
 * @route POST /
 * @param Book $book {@bind request.request} 这里将 post 的内容绑定到 book 参数上
 * @throws BadRequestHttpException
 * @return string 返回新建图书的编号
 */
public function createBook(Book $book)
{
    return '123';
}

请求中的 json 会被框架自动转换成函数中需要的对象参数。
{@bind request.request} 表示用请求的 body 构造 $book 变量，若不指定 @bind，默认是提取请求 body 中 "book" 字段构造 $book 变量，也就是说请求会是以下形式：

{
    "book": {
            "id": 0,
            "name": "string",
            "brief": "string",
            "pictures": [
                "string"
            ]
        }
}

删除图书

/**
 * 删除图书
 *
 * @route DELETE /{id}
 * @param string $id
 * @throws NotFoundHttpException 指定图书不存在
 * @return void
 */
public function deleteBook($id)
{
    
}

如果函数没有返回值，则响应的 http body 会是 void，而不是空字符串, 因为基于 PhpBoot 实现的接口，默认情况下，http body 总是 json，而空字符串并不是合法的 json。

更多内容见:

下期将介绍 PhpBoot 数据库部分的使用，敬请期待。

如需帮助可以联系 caoyangmin@gmail.com ，或者加入 QQ 群：185193529

PhpBoot 入门（一） 快速开发 RESTful 接口