lumen7+Dingo API 3原创教程

准备工作

前言

当前官方Lumen最新版本：7.1.3
当前官方Dingo最新版本：3.0
项目根目录：/home/wwwroot/blog
项目域名：api.kimphp.com

创建项目安装扩展

创建Lumen7项目

cd /home/wwwroot/ && composer create-project --prefer-dist laravel/lumen blog

安装Dingo3扩展支持

cd /home/wwwroot/blog && composer require dingo/api

配置Nginx让项目跑起来

配置vhost信息

server
    {
        listen 80;
        #listen [::]:80;
        server_name api.kimphp.com ;
        index index.html index.htm index.php default.html default.htm default.php;
        root  /home/wwwroot/blog/public;

        include rewrite/laravel.conf;
        #error_page   404   /404.html;

        # Deny access to PHP files in specific directory
        #location ~ /(wp-content|uploads|wp-includes|images)/.*\.php$ { deny all; }

        # 
        include enable-php.for.laravel-thinkphp5-yii2.conf;
        location ~ .*\.(gif|jpg|jpeg|png|bmp|swf)$
        {
            expires      30d;
        }

        gzip_types     text/plain application/javascript application/x-javascript text/javascript text/css application/xml application/xml+rss application/json;
            
        add_header Access-Control-Allow-Origin *;
        add_header Access-Control-Allow-Credentials true;
        add_header Access-Control-Allow-Methods 'GET,POST,DELETE,PUT,OPTIONS';
        add_header Access-Control-Allow-Headers 'Keep-Alive,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Authorization,Channel-Id,Version,OS,Bundle,Unique-Id,Device,Accept';
        #不需要缓存注释下面这条
        #add_header Cache-Control 'no-cache, no-store, max-age=0, must-revalidate';

        if ($request_method = 'OPTIONS') {
            return 200;
        }

        location ~ .*\.(js|css)?$
        {
            expires      12h;
        }

        location ~ /.well-known {
            allow all;
        }

        location ~ /\.
        {
            deny all;
        }

        access_log off;
    }

检查域名解析是否正常

如果以上操作一切正确，则会显示下图：

开启Lumen7+Dingo3的旅程

基础设置

注册服务提供者

打开 bootstrap/app.php 并注册服务提供者：

$app->register(Dingo\Api\Provider\LumenServiceProvider::class);

添加.env配置信息

#标准树(有三种不同的树：未注册的树x主要用于本地或私有环境，个人树prs主要用于非商业发行的项目，供应商树vndvnd主要用于可公开获得和分发的项目。您使用的标准树将取决于您正在开发的项目。)
API_STANDARDS_TREE=x
#亚型(子类型通常是应用程序或项目的缩写全为小写。)
API_SUBTYPE=blog
#前缀
API_PREFIX=/
#域(也就是项目网址)
API_DOMAIN=api.kimphp.com
#默认API版本
API_VERSION=v1
#API名称
API_NAME="KIM PHP API"
#条件请求状态（默认情况下，条件请求处于启用状态，因为它将在可能的情况下利用客户端缓存功能来缓存API请求。）
API_CONDITIONAL_REQUEST=false
#严格模式（严格模式将要求客户端发送Accept标头，而不是默认使用配置文件中指定的版本。这意味着您将无法通过Web浏览器浏览API。如果启用了严格模式并且使用了无效的Accept头，那么API将抛出未处理的内容Symfony\Component\HttpKernel\Exception\BadRequestHttpException，您应该适当地对其进行处理。）
API_STRICT=true
#默认响应格式
API_DEFAULT_FORMAT=json
#调试模式
API_DEBUG=true

设置错误返回格式

打开 bootstrap/app.php 在末端添加：

$app['Dingo\Api\Exception\Handler']->setErrorFormat([
    'error' => [
        'message' => ':message',
        'errors' => ':errors',
        'code' => ':code',
        'status_code' => ':status_code',
        'debug' => ':debug'
    ]
]);

如下图：

创建API路由配置文件

在项目（blog/routes）目录下创建一个api.php文件用于设置api路由

启用API路由配置文件

编辑（blog/bootstrap/app.php）在下图所示位置添加

require __DIR__.'/../routes/api.php';

Hello World

创建api接口

简单版（直接在路由中完成接口）

编辑刚创建的API路由配置文件blog/routes/api.php

<?php
$api = app('Dingo\Api\Routing\Router');
/** @var Dingo\Api\Routing\Router $api */
$api->version('v1', function ($api) {
    /** @var Dingo\Api\Routing\Router $api */
    $api->get('hello_world', function () {
        return ['Hello World v1'];
    });
});
/** @var Dingo\Api\Routing\Router $api */
$api->version('v2', function ($api) {
    /** @var Dingo\Api\Routing\Router $api */
    $api->get('hello_world', function () {
        return ['Hello World v2'];
    });
});

进阶版（通过路由+控制器完成接口）

创建控制器controller

在blog/app/Http/Controllers下创建v1和v2两个目录用于存放不同版本的接口，并在2个目录中各自创建一个HelloWorldController.php文件，具体演示代码如下：

blog/app/Http/Controllers/v1/HelloWorldController.php

<?php

namespace App\Http\Controllers\v1;

use App\Http\Controllers\Controller;

class HelloWorldController extends Controller
{
    /**
     * Create a new controller instance.
     *
     * @return void
     */
    public function __construct()
    {
        //
    }

    //
    public function index()
    {
        return ['hello world v1'];
    }
}

blog/app/Http/Controllers/v2/HelloWorldController.php

<?php

namespace App\Http\Controllers\v2;

use App\Http\Controllers\Controller;

class HelloWorldController extends Controller
{
    /**
     * Create a new controller instance.
     *
     * @return void
     */
    public function __construct()
    {
        //
    }

    //
    public function index()
    {
        return ['hello world v2'];
    }
}

设置API接口路由

编辑刚创建的API路由配置文件blog/routes/api.php

<?php
$api = app('Dingo\Api\Routing\Router');
/** @var Dingo\Api\Routing\Router $api */
$api->version('v1', ['namespace' => 'App\Http\Controllers\v1'],function ($api) {
    /** @var Dingo\Api\Routing\Router $api */
    $api->get('hello_world','HelloWorldController@index');
});
/** @var Dingo\Api\Routing\Router $api */
$api->version('v2', ['namespace' => 'App\Http\Controllers\v2'],function ($api) {
    /** @var Dingo\Api\Routing\Router $api */
    $api->get('hello_world','HelloWorldController@index');
});

访问api接口

需要在header请求头部添加Accept，
Accept的值：

v1版
application/x.blog.v1+json

v2版
application/x.blog.v2+json

当.env中API_STRICT=true时代表接口运行在严格模式下，此时访问接口必须添加Accept

Eolinker示例：

Postman示例

如果像上图一样的返回则代表一切正常，恭喜你，关于header头的说明：

Accept：application/x.blog.v1+json
x代表：API_STANDARDS_TREE=x
blog代表：API_SUBTYPE=blog
v1代表：访问接口版本v1
json代表json返回

返回如上图结果代表一切正常