README

Bricre - Symfony API Platform - 样板项目

这是一个基于 API Platform 的样板项目，可以帮助您快速开始一个现成的微服务项目。

先决条件

• Docker Desktop
• Docker Compose
• Mutagen

设置

在 Docker 环境中运行 composer update 需要大量的内存，请增加 内存资源，否则更新可能会失败而不会显示错误。

docker run --rm -it -v $(pwd):/app composer create-project bricre/symfony-boilerplate  .

docker run --rm -it -v $(pwd):/app composer php bin/console assets:install --relative

docker-compose up -d

mutagen project start

更新 .env 文件

MICROSERVICE=test

使用 MICROSERVICE 环境变量来确定将要路由的微服务的路径。

在这个例子中，我们将它设置为 test，因此服务将通过 /api/test/ 可访问，如下所示。

如果我们将其设置为 user，则服务将通过 /api/user 可访问（需要相应地应用正确的 Kong 配置。）

由于这是一个微服务项目，我们将在所有微服务的前端放置 Kong 网关，无论它是基于 PHP 的 API 服务（如本项目），还是基于 ReactJS 的前端界面。所有流量都将通过 Kong 进入。

要运行此项目，我们需要运行以下命令（端口 8001 是默认的 Kong 管理API端口）

# Set service and route for Konga (a Kong web admin ui)
curl -i -X POST \
  --url http://localhost:8001/services/ \
  --data 'name=konga' \
  --data 'host=konga' \
  --data 'port=1337'

curl -i -X POST \
  --url http://localhost:8001/services/konga/routes \
  --data 'name=konga' \
  --data 'paths[]=/konga/' 

# Set service and routes for the microservice (nginx) we are working on
curl -i -X POST \
  --url http://localhost:8001/services/ \
  --data 'name=test' \
  --data 'host=nginx'

curl -i -X POST \
  --url http://localhost:8001/services/test/routes \
  --data 'name=test-secured' \
  --data 'paths[]=/api/test/' \
  --data 'strip_path=false' \
  --data 'preserve_host=true'

# _profiler and _wdt are for dev environment only
curl -i -X POST \
  --url http://localhost:8001/services/test/routes \
  --data 'name=test-public' \
  --data 'paths[]=/api/test/_profiler' \
  --data 'paths[]=/api/test/_wdt' \
  --data 'paths[]=/api/test/login' \
  --data 'paths[]=/api/test/docs' \
  --data 'strip_path=false' \
  --data 'preserve_host=true'

# The 'assets' directory is only used in dev environment for web profiler to correctly work
# Notice we delirately put strip_path=true, this is the only way I can get it working easily.
curl -i -X POST \
  --url http://localhost:8001/services/test/routes \
  --data 'name=test-assets' \
  --data 'paths[]=/api/test/assets/' \
  --data 'strip_path=true' \
  --data 'preserve_host=true'

阅读 Kong 入门指南 了解如何自定义路由。

您也可以使用用户名 kong 和密码 password 访问 http://localhost:8000/konga/，详情见 docker/kong_user.js

Mutagen

由于 Symfonly 严重利用自动装配和自动配置，在开发环境中，每次更新源代码时都会重新编译整个依赖注入系统。这导致了由于访问的文件数量而导致的性能问题，尤其是在 Mac & Windows 平台的 Docker 下。

直到 Docker 修复了这个问题，我们使用 Mutagen 来提高文件系统性能。

在 docker-compose.yaml 中，我们指定了一个 container_name，稍后在 mutagen.yml 中使用它，见 sync:codebase:beta。

如果您同时运行多个项目，请记住更改 container_name 以避免冲突。

注意：为了获得更好的系统性能，我们忽略了 vendor/ 文件夹，它只会在您启动 Mutagen 项目时刷新。

如果您安装了新的 composer 模块，但发现它没有包含在您的项目中，只需运行以下脚本重新启动 Mutagen 即可

mutagen project terminate
mutagen project start

开发

现在可以通过 http://localhost:8000/api/test 访问网站，您应该看到 Symfony 默认欢迎屏幕。

数据库

使用您喜欢的桌面工具通过以下设置连接到数据库

通过 SSH 连接

• 主机: 127.0.0.1
• 端口: 2222
• 用户名: root
• 密码: root

连接到数据库

• 主机: db
• 用户名: root
• 密码: password
• 数据库名: db_name

在创建数据库模式后，运行以下脚本以生成相关的Doctrine文件

docker-compose exec php /var/www/html/bin/console doctrine:mapping:import "App\Entity" annotation --path=src/Entity

上述行生成的代码不会创建Repository类，为此您需要在每个新的Entity模型类中添加自定义Entity引用的PHPDoc。

假设我已创建了一个User实体类，我需要将类注释从

use Doctrine\ORM;
/**
 * TestUser
 *
 * @ORM\Table(name="user")
 * @ORM\Entity
 */
class User{}

改为

use Doctrine\ORM;
/**
 * TestUser
 *
 * @ORM\Table(name="user")
 * @ORM\Entity(repositoryClass="App\Repository\UserRepository")
 */
class User{}

然后运行

docker-compose exec php /var/www/html/bin/console make:entity --regenerate

这将为您生成一个可工作的Repository类。

API开发

一旦您将@ApiResource()添加到一个实体上，它将自动成为API资源。

use ApiPlatform\Core\Annotation\ApiResource;
use Doctrine\ORM;
/**
 * TestUser
 * @ApiResource()
 * 
 * @ORM\Table(name="user")
 * @ORM\Entity(repositoryClass="App\Repository\UserRepository")
 */
class User{}

我们可以访问http://localhost:8000/api/test/docs以与生成的API端点交互。

请阅读api-platform.com以获取更多API开发相关指南。

调试

Swagger UI底部的WebProfiler工具栏是开始诊断的好地方。

xDebug已安装在PHP中，并且应该使用默认设置工作。

如果您的调试会话没有自动启动，并且您确定您已正确设置了一切，请尝试重新启动PHPStorm。我发现这总是有帮助的，PHPStorm有时即使您切换了调试按钮，也会停止监听9000端口。只有重新启动才能解决问题。