路由案例

路由案例模板

# <endpoint> route trace
 
文件狀態：草稿 / 已對 legacy / 已對 new API / 已實測
最後驗證：YYYY-MM-DD
來源：legacy code / new code / ALB access log / staging curl
 
## 要回答的問題
 
這份案例只回答如何從外部 URL 找到 legacy 與 new API 的入口程式。
 
不回答完整 business rule、付款規則、DB side effect。
 
## 1. 先確認目前實際流量
 
查 AWS ALB access log、專案 migration detail 或既有 access log 紀錄。
 
要確認：
 
- host
- path
- method
- `.json` / `.xml`
- path params
- named params
- body params 是否影響 route
 
## 2. 找 legacy 入口
 
先查：
 
```text
app/Config/routes.php
app/Config/cms_routes.php
```
 
若 routes 沒有明確定義，再用 CakePHP convention 找：
 
```text
app/Plugin/<Plugin>/Controller/<Controller>Controller.php
::<action>()
```
 
再追 controller 呼叫的 model/domain method。
 
## 3. 找 new API 入口
 
先查 router：
 
```text
Lib/Common/RouterV3.php
Lib/Common/RouterRule/Mapping.php
Lib/Common/RouterRule/Origin.php
Lib/Common/RouterRule/File.php
```
 
查詢順序：
 
```text
Mapping
-> Origin
-> File fallback
```
 
## 4. 什麼時候查 Mapping.php
 
- URL 字面上的 controller/action 找不到 endpoint file。
- endpoint method 存在但 URL 打不到。
- legacy URL 和 new endpoint/action 名稱不同。
- path params 需要被改寫。
- 同一 endpoint action 支援多個 legacy-compatible URL。
 
## 5. 確認 endpoint params
 
列出：
 
| 值 | 來源 |
|---|---|
| `<id>` | rawParams / named params / body |
| `<status>` | named params / body |
 
## 6. 相關文件
 
- [[../API 路由與遷移/new_api_routing]]
- [[../API 路由與遷移/legacy_cakephp_routing]]
- [[../API 路由與遷移/endpoint_migration_checklist]]