Symfony6中Form/Controller与API Platform整合及代码复用最佳实践

一、两者共存并非不良实践 #

这是完全合理且常见的项目架构：很多场景下项目需要同时支持传统表单提交（如后台管理、用户端页面）和API接口（如移动端、SPA前端），共享核心业务逻辑和实体定义能极大减少重复代码，提升维护效率。无需担心架构冲突，Symfony和API Platform本身就设计为可灵活组合使用。

二、具体整合方案 #

1. 复用User Schema #

直接在同一个User实体上同时保留Doctrine ORM注解和API Platform注解即可，无需拆分实体。示例：

// src/Entity/User.php
namespace App\Entity;

use Doctrine\ORM\Mapping as ORM;
use ApiPlatform\Core\Annotation\ApiResource;
use Symfony\Component\Security\Core\User\UserInterface;

#[ORM\Entity(repositoryClass: UserRepository::class)]
#[ApiResource(
    collectionOperations: ['post'],
    itemOperations: ['get'],
)]
class User implements UserInterface
{
    // ... 原有Doctrine字段注解、UserInterface实现逻辑
    #[ORM\Column(type: 'string')]
    private string $password;
    
    // 用于表单和API的明文密码（非持久化）
    private ?string $plainPassword = null;
    
    // ... getter/setter方法
}

这样表单和API都会基于同一个实体进行数据处理，自动复用字段规则和验证逻辑。

2. 统一密码哈希逻辑 #

将密码哈希逻辑抽离为独立服务，替代控制器和DataPersister中的重复实现：

// src/Service/PasswordHasherService.php
namespace App\Service;

use App\Entity\User;
use Symfony\Component\PasswordHasher\Hasher\UserPasswordHasherInterface;

class PasswordHasherService
{
    public function __construct(private UserPasswordHasherInterface $passwordHasher) {}

    public function hashUserPassword(User $user): void
    {
        if ($user->getPlainPassword()) {
            $hashedPassword = $this->passwordHasher->hashPassword(
                $user,
                $user->getPlainPassword()
            );
            $user->setPassword($hashedPassword);
            $user->eraseCredentials();
        }
    }
}

在RegistrationController中调用

// src/Controller/RegistrationController.php
public function register(Request $request, PasswordHasherService $passwordHasherService, EntityManagerInterface $entityManager): Response
{
    $user = new User();
    $form = $this->createForm(RegistrationFormType::class, $user);
    $form->handleRequest($request);

    if ($form->isSubmitted() && $form->isValid()) {
        $passwordHasherService->hashUserPassword($user);
        
        $entityManager->persist($user);
        $entityManager->flush();

        return $this->redirectToRoute('app_login');
    }

    return $this->renderForm('registration/register.html.twig', [
        'registrationForm' => $form,
    ]);
}

在UserDataPersister中调用

// src/DataPersister/UserDataPersister.php
namespace App\DataPersister;

use App\Entity\User;
use App\Service\PasswordHasherService;
use Doctrine\ORM\EntityManagerInterface;
use ApiPlatform\Core\DataPersister\DataPersisterInterface;

class UserDataPersister implements DataPersisterInterface
{
    public function __construct(
        private EntityManagerInterface $entityManager,
        private PasswordHasherService $passwordHasherService
    ) {}

    public function supports($data): bool
    {
        return $data instanceof User;
    }

    public function persist($data): void
    {
        $this->passwordHasherService->hashUserPassword($data);
        $this->entityManager->persist($data);
        $this->entityManager->flush();
    }

    public function remove($data): void
    {
        $this->entityManager->remove($data);
        $this->entityManager->flush();
    }
}

3. 让RegistrationFormType适配API #

Symfony Form组件原生支持处理JSON等API请求，只需调整表单配置：

// src/Form/RegistrationFormType.php
namespace App\Form;

use App\Entity\User;
use Symfony\Component\Form\AbstractType;
use Symfony\Component\Form\FormBuilderInterface;
use Symfony\Component\OptionsResolver\OptionsResolver;
use Symfony\Component\Form\Extension\Core\Type\PasswordType;
use Symfony\Component\HttpFoundation\RequestStack;

class RegistrationFormType extends AbstractType
{
    public function __construct(private RequestStack $requestStack) {}

    public function buildForm(FormBuilderInterface $builder, array $options): void
    {
        $builder
            ->add('email')
            ->add('plainPassword', PasswordType::class, [
                'mapped' => false,
                'attr' => ['autocomplete' => 'new-password'],
            ]);
    }

    public function configureOptions(OptionsResolver $resolver): void
    {
        $request = $this->requestStack->getCurrentRequest();
        
        $resolver->setDefaults([
            'data_class' => User::class,
            // 仅对API请求关闭CSRF保护
            'csrf_protection' => !$request || !$request->isXmlHttpRequest(),
            // 允许表单直接处理JSON数据
            'allow_extra_fields' => false,
        ]);
    }
}

如果需要专门为API写控制器，也可复用该表单：

// src/Controller/ApiRegistrationController.php
namespace App\Controller;

use App\Entity\User;
use App\Form\RegistrationFormType;
use App\Service\PasswordHasherService;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\JsonResponse;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Annotation\Route;

class ApiRegistrationController extends AbstractController
{
    #[Route('/api/register', name: 'api_register', methods: ['POST'])]
    public function register(Request $request, PasswordHasherService $passwordHasherService): JsonResponse
    {
        $user = new User();
        $form = $this->createForm(RegistrationFormType::class, $user);
        
        // 解析JSON请求并提交表单
        $form->submit(json_decode($request->getContent(), true));

        if ($form->isValid()) {
            $passwordHasherService->hashUserPassword($user);
            
            $em = $this->getDoctrine()->getManager();
            $em->persist($user);
            $em->flush();

            return $this->json([
                'id' => $user->getId(),
                'email' => $user->getEmail()
            ], Response::HTTP_CREATED);
        }

        // 返回结构化表单错误
        return $this->json([
            'errors' => $this->formatFormErrors($form)
        ], Response::HTTP_BAD_REQUEST);
    }

    private function formatFormErrors(\Symfony\Component\Form\FormInterface $form): array
    {
        $errors = [];
        foreach ($form->getErrors() as $error) {
            $errors[] = $error->getMessage();
        }
        foreach ($form->all() as $child) {
            if ($childErrors = $this->formatFormErrors($child)) {
                $errors[$child->getName()] = $childErrors;
            }
        }
        return $errors;
    }
}

4. 保留AbstractController核心方法 #

只要控制器继承AbstractController，createForm、handleRequest、renderForm等方法都可正常使用：

• 传统表单场景：用handleRequest处理HTTP表单提交，renderForm渲染Twig模板；
• API场景：用submit手动处理JSON数据，返回JsonResponse即可，无需调用renderForm。

内容的提问来源于stack exchange，提问作者guibs35