README

目录

• 关于库
  • 安装
  • 描述
  • 术语和定义
  • 原则和架构
• 创建端点
  • 创建 Request 类
  • 创建 Response 类
  • 创建端点
  • 集成到 laravel 5.4+
• 使用示例
  • 使用端点
  • 在 laravel 5 中使用端点
  • 创建文档
  • 在 Laravel 5 中创建文档

关于库

安装

回到目录

在项目的 composer 中添加以下行

    "repositories": [
        {
            "type": "vcs",
            "url":  "gogs@gogs.inetpartners.org:archee-nic/decl-api.git"
        }
    ]

然后在控制台可以写下 composer require archee-nic/decl-api

描述

回到目录

DeclApi - 声明式API库

这意味着，开发者首先描述获取和返回信息的规则，然后再编写实际的逻辑

该库实现时与任何框架的最大隔离。

由于实现了声明式逻辑，因此可以生成文档并自动测试API的可用性。

由于与框架的隔离，迁移将更加平滑，而父架构将保持不变

由于...

术语和定义

回到目录

EndPoint - 具有自身逻辑的URI。

EndPoint 类 - 具有端点逻辑的类

API 对象 - 包含单个级别数据的类

Request 类 - 包含有关传入数据的API对象

原则和架构

回到目录

...

创建端点

创建 Request 类

回到目录

Request 与普通对象的区别在于，它的输入数据是字段组的数组：json、parameter（get、post）、header

在 App/Api 文件夹中创建用于处理输入数据的 ExampleRequest 文件

    <?php namespace App\Api;

    use DeclApi\Core\Request;

    class ExampleRequest extends Request
    {
    }
    ?>

添加对传递参数的 get/post 规则

    /**
     * @throws \Exception
     */
    protected function initRules()
    {
        parent::initRules();
        $this->rulesInfo()->add('parameter','integer','example','Пример поля','Пример описания поля')->setDefault(10)->setAttributes('required');
    }

创建 Response 类

回到目录

Response 类 - 普通对象 - ObjectClass，为了方便起见，建议以 Response 结尾命名，以便理解对象的用途

在 App/Api 文件夹中创建用于处理输入数据的 ExampleRequest 文件

<?php namespace App\Api;

use DeclApi\Core\ObjectClass;

class ExampleResponse extends ObjectClass
{
}

添加对存储参数的规则

    /**
     * @throws \Exception
     */
    protected function initRules()
    {
        parent::initRules();
        $this->rulesInfo()->add('integer','example','Пример параметра','Описание параметра');
    }

创建端点

回到目录

我们将以 laravel 5 为例进行讨论

在 app/Http 文件夹中创建子文件夹 Api

文件夹的名称和位置无关紧要，仅限于架构和框架设置。

Laravel 5 中的 api.php 使用 app/Http 作为搜索路由目标的默认文件夹

在文件夹内创建名为 ExamplePoint.php 的类，内容如下

<?php namespace App\Http\Api;

use DeclApi\Core\PointL5Bridge;

class ExamplePoint extends Laravel5Point
{

}

请注意，父类 PointL5Bridge 是将库集成到 Laravel 5 的桥梁。它是 Point 的子类。

如果需要在其他框架中实现，可以编写类似的桥接器并使用它。同样，也可以使用纯净的Point。

现在我们将方法添加到创建的类中。

    /**
     * @param ExampleRequest $request
     *
     * @return ExampleResponse
     * @throws \Exception
     */
    public function handler(ExampleRequest $request): ExampleResponse
    {
        $data = new ExampleResponse();
        return $data;
    }

在类上方添加使用的命名空间。

use App\Api\ExampleRequest;
use App\Api\ExampleResponse;

与laravel 5.4+的集成

回到目录

因为我们使用了laravel 5的桥接器作为父类，所以不需要编写任何特殊的规则或建立库的连接

在api.php中添加一行

Route::get('/example','Api\ExamplePoint');

现在我们的Point将在URI /api/example的请求中被调用

工作原理

简要介绍结构

1. 端点

为每个端点创建一个包含通过handler调用的逻辑的类。

• 输入的类包含传入数据的结构描述。（与request不同，那里存储的是数据而不是像头部抓取这样的魔法）
• 输出的类包含返回数据的结构和数据本身。

简要利润：严格性、可预测性、最新的文档、可重用性、自测试性

详细利润:

1. 严格性：你不能简单地返回一个字符串或数组。方法总是等待返回一个DeclApiObject实例，它负责存储数据。
2. 可预测性：在DeclApiObject中查找规则和字段。（类似于validator）。如果它们与预期不同（例如，多余的字段）- 将抛出异常。这保证了在使用Select *时，用户不会收到意外的多余数据。
3. 最新的文档：生成器根据调用方法、输入类的名称和输出生成文档。它创建OpenApi3格式的文档（技术上已埋入扩展生成器到BluePrint格式的能力）。因此，每次更改API时，不需要重新构建文档
4. 可重用性：因为类具有一个独立且预先协商好的输入/输出数据逻辑，所以可以在控制台或其他任何地方调用它。
5. 自测试性：根据与文档相同的原理，类可以生成输入和输出测试数据。还可以尝试执行代码。

2. 桥接器

由于实现的类端点是自给自足的，它们可以与laravel的“路由特性”一起使用，即使用类通过__invoke进行路由。因此，与Laravel的轻松集成。同样，与不同的文档。通用标准允许生成器获取预先准备好的数据并按自己的方式定制

3. 验证

使用illuminate/validation进行字段验证

推荐的文件结构

• Api - Api根目录
  • v1 - API分区子目录
  • configs - 配置文件子目录