迁移指南

迁移建议是“渐进式”，不要一次改完。

推荐迁移顺序

1. 保留现有 Service 层
2. 新接口先用 defineApi
3. 旧接口按模块逐步迁移
4. 关键接口补齐 input/output
5. 稳定后再删除旧 controller

共存策略

同一个项目里，@Controller 和 defineApi 可以直接共存，不需要强制分层或隔离。

按场景选择即可：

• 需要和前端协同开发：优先 defineApi
• 纯后端 API 提供：两种写法都可用

Midway 会按 method + fullPath 做冲突检测。

常见问题

前端可以直接执行后端 handler 吗？

不能。前端只复用契约和类型，真实逻辑仍在服务端执行。

必须用 src/server、src/web 吗？

不是，目录可以自定义。文档里的结构是推荐默认值。

要一次性给所有接口补 schema 吗？

不用。先覆盖高风险接口，再逐步补齐即可。