README

A 代码生成工具。从构建强类型、模式化的HTTP应用中去除繁琐的工作。

入门

安装

可以使用 Composer 安装 Prefab

composer require neighborhoods/prefab

运行 Prefab

在您的 composer 文件中，确保您已经定义了项目名称。使用 Prefab 根目录下的 composer-example.json 文件作为模板
根据以下说明创建您的 Actor.prefab.definition.yml 文件。
从项目的根目录运行 ./vendor/bin/prefab
- 这将添加创建工作API端点所需的所有支持文件

Prefab 适应性

要查看Prefab的使用示例，请查看Prefab Fitness 存储库，其中包含可以在本地运行的全自包含环境示例。

先决条件

PSR-4 命名空间定义

Prefab 假设用户在他们的 composer.json 文件中的 autoload 键下已定义 psr-4 命名空间。命名空间必须定义为 {VENDOR}\{PRODUCT_NAME}。有关更多信息，请参阅composer 文档。Prefab 将在项目根目录下的 fab/ 目录中写入生成的文件。您应该配置您的自动加载器，首先在 src/ 中查找，然后是 fab/。这将允许您通过将类的新副本放在等效的 src/ 位置来覆盖生成的文件。

示例

"autoload": {
    "psr-4": {
      "Neighborhoods\\MyPrefabbedProject\\": [
        "src",
        "fab"
      ]
    }
}

环境变量

Prefab 预期以下环境变量已被定义。

项目结构

Prefab 需要所有 Prefab 定义文件都位于 src/ 下的版本化目录中。例如，src/V1/Actor.prefab.definition.yml 是有效的，而 src/Actor.prefab.definition.yml 则不是。

物化视图

Prefab 极其关注性能。Prefab 实现快速响应时间的一种方式是通过确保所有 HTTP 请求都导致对索引的单次数据库查询，这是通过使用物化视图实现的。Prefab 使用搜索条件与其数据库交互，该数据库不支持表连接。这意味着给定请求的所有数据必须位于同一表中。

注意：由于搜索条件允许您选择要返回的数据，因此可以使用包含您HTTP端点返回的所有数据的超集的单个物化视图。

Prefab 定义文件规范

本文档的目的是定义从 .prefab.definition.yml 文件生成演员HTTP端点所需组件。

文件必须命名为 {ACTORNAME}.prefab.definition.yml，并保存在 src/ 下。它们应存储在与您希望在 fab/ 下生成的机械相同的嵌套目录结构中。

table_name
- 包含填充演员的数据的数据库表名称
supporting_actor_group
- 为演员生成所需的支持演员集合
- 可以是以下之一：complete、collection、minimal、handler或repository
- 此字段为可选字段，默认为complete
- 更多信息请参阅以下内容
tag_filter_fields_on_tracer
- 此字段为可选字段，默认为false
- 如果您想将所有发送到Map\Repository\Handler的所有筛选字段标记为默认全局跟踪器，则设置为true。
- 注意：为了访问全局跟踪器，代码使用neighborhoods/datadog-component包。除非您在端点的http-buildable-directories.yml文件中的appended_paths列表中包含包源路径，否则您的端点将不会构建Symfony容器。源路径通常是vendor/neighborhoods/datadog-component/src。
json_serialize_map_as_array
- 此字段为可选字段，默认为false
- 当HTTP响应包含演员映射时，应设置为true，此时响应应为JSON数组而不是具有数值属性名的对象。
http_route
- 访问演员的HTTP路由
- 此字段为可选字段，如果您不想将演员暴露给HTTP流量，则不需要此字段。
http_verbs
- 允许的演员HTTP方法。可以包括GET、POST、PUT、PATCH和DELETE。
- 注意：由于尚未为存储库设计模式化可变和破坏性操作，您将需要覆盖生成的处理程序来调用正确的存储库方法。
constants
- 添加到演员接口的额外用户定义常量。
- 此字段为可选字段
identity_field
- 数据库列名称，用于唯一标识演员的记录
properties
- 演员的类属性。每个属性应具有以下内容：
  - data_type
    - 属性表示的对象类型。这可以是原始类型或完全限定的命名空间对象
    - 注意：这曾经被称为php_type，为了向后兼容而保留。
  - record_key
    - 包含填充类属性的数据的键的名称
    - 如果没有设置，则默认为属性名称
    - 注意：这曾经被称为database_column_name，仍然保留以供向后兼容。
  - nullable
    - 此属性是否可以为null。如果为true，则在尝试在演员上设置值之前，构建方法将使用isset()包围此属性
    - 如果没有设置，则默认为false
  - created_on_insert
    - 这表示在将记录插入数据库之前不期望存在的属性。
    - 如果为true，则buildForInsert()方法将在尝试在演员上设置值之前使用isset()包围此属性。但是，构建()方法在从数据库构建记录时仍需要此属性。
    - 如果没有设置，则默认为false

示例 Prefab 定义文件

文件名：User.prefab.definition.yml

table_name: mv1_user
identity_field: id
supporting_actor_group: complete
http_route: /mv1/users/{searchCriteria:}
http_verbs:
- get
- post
- put
- patch
- delete
constants:
  SOME_CONSTANT: some value
  NUMERIC_CONSTANT: 2.123
  ARRAY_CONSTANT_WITH_KEYS:
    some_key: some_value
    some_nested_array:
    - 123
    - test
  ARRAY_CONSTANT_WITHOUT_KEYS:
  - 1
  - 3
  - TEST
properties:
  id:
    data_type: int
    nullable: false
    created_on_insert: true
  email:
    data_type: string
    nullable: true
  first_name:
    data_type: string
    nullable: false
  last_name:
    data_type: string
    nullable: false
  created_at:
    data_type: string
    nullable: false
    created_on_insert: true

搜索条件

搜索条件是一种数据挖掘查询语言（DMQL），由Prefab应用程序使用，以提供灵活的API，允许HTTP客户端定义他们想要如何请求数据，而不是显式实现每个用例。搜索条件由筛选器以及可选的排序顺序和分页说明组成。

过滤器

搜索条件筛选器用于定义数据库查询的WHERE子句。筛选器应包含在searchCriteria[filters]键下的数组中。每个筛选器由以下内容组成

查询参数键：searchCriteria[filters]

条件

排序方式

排序顺序用于定义数据返回的顺序。它由一个包含字段和方向的数组组成。

查询参数键：searchCriteria[sortOrder]

分页

可以通过定义页面大小来限制查询返回的结果数量。通过在键 searchCriteria[pageSize] 下提供一个整数来设置页面大小。通过提供一个当前页码，可以检索额外的数据页。通过在键 searchCriteria[currentPage] 下提供一个整数来设置当前页码。

支持的角色组

预制件支持生成不同的支持演员子集，以支持各种用例。有关如何指定支持演员组的详细信息，请参阅预制件定义文件规范。以下支持演员组可用：

complete - 生成所有支持演员。在需要能够从存储中构建演员并通过HTTP返回它时，应使用此选项。
- 包含的支持演员：
  - 工厂
  - 构建器
  - 感知特性
  - 存储库
  - 映射
  - 映射构建器
  - 处理器
collection - 生成用于构建和处理类型化对象组的支持演员。这通常用于在JSON数据库列中表示演员的集合。
- 包含的支持演员：
  - 工厂
  - 构建器
  - 感知特性
  - 映射
  - 映射构建器
minimal - 生成构建演员所需的最少支持演员数。这可以用于表示单个类型化对象。
- 包含的支持演员：
  - 工厂
  - 构建器
  - 感知特性
handler - 仅生成处理器实例。除了Buphalo生成的演员外，还可以使用此功能提供HTTP功能。请参阅存储库处理器文档
- 包含的支持演员：
  - 处理器
repository - 生成拥有映射存储库所需的最少支持演员数。在需要从外部源（例如，从HTTP API）检索演员，但不需要在服务本身上公开端点时，应使用此选项。
- 包含的支持演员：
  - 工厂
  - 构建器
  - 感知特性
  - 存储库
  - 映射
  - 映射构建器

子集容器可构建目录

随着Symfony容器的增大，HTTP请求的响应时间也会增加。为了防止响应时间缓慢，预制件支持用户定义的子集容器构建。预制件用户可以为每个路由定义应包含在Symfony容器中的内容，因此只需初始化必要的演员。此可构建目录文件是可选的，如果找不到该文件，预制件默认将构建src/和fab/中的全部内容。如果文件存在，则所有路由必须具有相应的键，以及要构建的目录。

注意：在第一次请求时，预制件将此文件写入磁盘，作为目录data/cache/Opcache/HTTPBuildableDirectoryMap中的PHP数组。在修改可构建目录文件时，必须删除缓存文件，以便更改反映在代码中。还强烈建议在生产环境中启用Opcache，以防止每次HTTP请求都从磁盘读取。

top_level_key - 应该是URI。如果找不到URI前两部分的键，则预制件将检查只有第一部分的键。

示例：
- neighborhoods.com/mv1/property/{searchCriteria} 将构建以下示例文件中mv1/property键下的所有目录
- neighborhoods.com/mv2/property/{searchCriteria} 将构建以下示例文件中mv2键下的所有目录

buildable_directories - 表示给定请求希望包含的HTTP演员的目录。由于buildable_directories表示路径，应使用**正斜杠** (/) 作为分隔符。

示例
- 一个可构建目录的MV1/property将包含容器中的fab/MV1/property（如果存在）和src/MV1/property（如果存在）。

welcome_baskets - 这是预制件生成的HTTP机械的命名空间，应包含在请求中。由于welcome_baskets表示命名空间，应使用**反斜杠** (\) 作为分隔符。

示例
- Doctrine\DBAL将包括位于fab/Prefab5/Doctrine/DBAL下的Doctrine\DBAL命名空间下的所有文件。

appended_paths - 这些是您希望在容器中包含的任何附加路径，这些路径不在 fab/ 或 src/ 下。路径相对于您项目的根目录。由于 appended_path 表示路径，应使用 正斜杠 (/) 作为分隔符。

示例
- vendor/neighborhoods/throwable-diagnostic-component/src 将将 vendor/neighborhoods/throwable-diagnostic-component/src 文件夹下的所有文件包含在容器中。

示例

# Place this file at the root of your application.
mv1/property: # The URI to the component Handler.
  buildable_directories:
    - MV1/Property # The relative path to the directory of the component.
  welcome_baskets:
    - Doctrine\DBAL
    - PDO
    - Opcache
    - NewRelic
    - Zend\Expressive
    - SearchCriteria
  appended_paths:
    - vendor/neighborhoods/throwable-diagnostic-component/src
mv2: # The URI to the component Handler.
  buildable_directories:
    - MV2 # The relative path to the directory of the component.
  welcome_baskets:
    - Doctrine\DBAL
    - PDO
    - Opcache
    - NewRelic
    - Zend\Expressive
    - SearchCriteria
  appended_paths:
    - some/other/dir

默认情况下，Symfony 容器是在第一个 HTTP 请求时构建的。由于这可能会给第一个请求增加显著的时间，建议在处理生产流量之前预先构建容器。这可以通过在 bin/ 目录中添加以下脚本并在 composer.json 文件中将它作为 post-update-cmd 和/或 post-install-cmd 脚本包含进来，在 vendor/bin/prefab 之后实现。

#!/usr/bin/env php
<?php
declare(strict_types=1);
error_reporting(E_ALL);

require_once __DIR__ . '/../vendor/autoload.php';
use ReplaceThisWithYourVendorName\ReplaceThisWithTheNameOfYourProduct\Prefab5\HTTPBuildableDirectoryMap\ContainerBuilder;

$primer = new ContainerBuilder\Primer();
$primer->primeContainers();

return;

语义化版本控制

由于 Prefab 是一种代码生成工具，允许用户根据需要覆盖特定文件和行为，Prefab 无法保证小版本升级能与您的覆盖文件兼容。Prefab 确实保证纯 Prefab 项目（没有覆盖文件）的小版本升级不会出现任何破坏性更改。如果您确实覆盖了任何文件，重要的是您需要测试项目以验证这些文件在新版本的 Prefab 中仍然按预期工作。

调试模式

可以通过设置环境变量 DEBUG_MODE=true 启用调试模式。启用调试模式将在 HTTP 请求期间输出有关抛出的异常和错误的额外详细信息。如果在容器构建期间出现错误（例如，缺少 Symfony 服务文件），您将获得调试模式提供的额外可见性。调试模式将尝试将错误发送到 STDERR，并且它还将尝试将错误记录在 /Logs/HTTP.log 中。

neighborhoods / prefab

维护者

详情