PHP 老接口迁移变更单：从散落 $_POST 到 Request DTO 与统一错误响应

很多 PHP 老项目的接口入口层都很像：控制器里直接读 $_POST，某个字段先 trim，另一个字段转 int，业务方法里又补一次非空判断。短期看很快，接口多起来以后，参数规则、默认值、错误响应会散落在多个文件里，改一个字段就容易漏。

这篇文章按“迁移变更单”的方式，把散落参数读取迁到 Request DTO 和统一错误响应。目标不是引入庞大框架，而是先把入口层变清楚：请求进来先变成结构化对象，校验失败直接返回固定 JSON，业务层只拿干净参数。

升级范围：先迁入口层，不动业务主流程

第一轮迁移建议只碰接口入口层：控制器读取请求、字段类型转换、必填校验、错误响应格式。业务服务、数据库模型、返回数据结构先保持不动。这样可以把风险控制在请求边界，不会一次性牵连太多代码。

迁移后的链路应该是：

HTTP 请求
  -> Request DTO
  -> Validator
  -> Service
  -> JsonResponse

下面这张图展示了本次迁移的入口层变化：左边是散落读取参数，右边是 DTO 承接字段、统一校验，再把干净入参交给业务层。

变更表：旧写法和新写法怎么对应

迁移前先做一张小表，明确哪些行为需要保持兼容，哪些行为要统一。

旧代码风险：散落 $_POST 为什么越来越难维护

先看一个常见旧入口：

 400, 'msg' => 'name required']);
        return;
    }

    if ($age  120) {
        echo json_encode(['code' => 400, 'msg' => 'age invalid']);
        return;
    }

    $id = UserService::create($name, $age, $email);
    echo json_encode(['code' => 0, 'data' => ['id' => $id]]);
}

这段代码能跑，但问题会在接口增长后出现：字段默认值没有统一约定，错误码不稳定，业务方法参数靠位置传递，一旦新增字段就需要重新检查多个分支。更麻烦的是，有些接口把校验放在控制器，有些放在 Service，排查线上问题时很难快速判断请求到底在哪一层被拒绝。

新写法：Request DTO、规则校验和统一错误响应

先定义一个轻量 DTO。它只做三件事：接收原始数组、完成基础类型转换、声明字段规则。

 fn () => $this->name !== '',
            'age' => fn () => $this->age >= 1 && $this->age  fn () => $this->email === '' || filter_var($this->email, FILTER_VALIDATE_EMAIL),
        ];
    }
}

再写一个最小校验器，返回第一个失败字段即可。老项目第一阶段不需要一次做成复杂规则引擎，先把规则集中起来更重要。

rules() as $field => $check) {
            if (!$check()) {
                return ['field' => $field, 'message' => $field . ' is invalid'];
            }
        }
        return null;
    }
}

控制器入口就能变薄：

name,
        age: $request->age,
        email: $request->email,
    );

    JsonResponse::ok(['id' => $id]);
}

统一响应也要固定结构，方便前端、日志和接口测试复用同一套判断：

 0, 'msg' => 'ok', 'data' => $data]);
    }

    public static function fail(int $httpCode, string $bizCode, array $detail): void
    {
        http_response_code($httpCode);
        self::send(['code' => $bizCode, 'msg' => 'request invalid', 'detail' => $detail]);
    }

    private static function send(array $body): void
    {
        header('Content-Type: application/json; charset=utf-8');
        echo json_encode($body, JSON_UNESCAPED_UNICODE);
    }
}

回归检查：用四组请求确认兼容性

迁移后不要只测正常请求。建议至少准备四组回归用例：缺少必填字段、字段类型异常、边界值、正常创建。每一组都要记录 HTTP 状态码、业务 code、detail 字段和数据库写入结果。

curl -X POST http://127.0.0.1/user/create \
  -d 'age=18&email=a@example.com'

curl -X POST http://127.0.0.1/user/create \
  -d 'name=Tom&age=abc'

curl -X POST http://127.0.0.1/user/create \
  -d 'name=Tom&age=120&email='

curl -X POST http://127.0.0.1/user/create \
  -d 'name=Tom&age=18&email=tom@example.com'

正常请求返回：

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": 1024
  }
}

异常请求返回：

{
  "code": "PARAM_ERROR",
  "msg": "request invalid",
  "detail": {
    "field": "name",
    "message": "name is invalid"
  }
}

迁移清单：按接口批次推进

最后给一份可以直接落地的迁移清单：

• 先挑 1 到 3 个低风险接口，记录原始请求、原始响应和数据库结果。
• 为每个接口建立独立 Request DTO，字段名暂时保持和旧接口一致。
• 把类型转换和必填规则从控制器搬到 DTO 或校验器。
• 统一错误 JSON，但保留原来的业务成功响应，减少调用方适配成本。
• 补齐四组回归请求，并把返回体保存到接口用例里。
• 迁移完成后，再考虑把重复规则抽成通用 Rule 类。

这类改造的关键不是一次把代码写得很“新”，而是把请求边界从模糊变清楚。DTO 让参数结构可见，校验器让错误原因集中，统一响应让调用方和排障日志更稳定。老 PHP 项目可以一批接口一批接口地迁，不需要冒着全量重写的风险。