---
name: "ulthon-page-api-dual-mode"
description: "指导控制器实现“页面/接口同体”。需要同一路由同时返回 HTML 与 JSON 时调用。"
---

# 页面 / 接口同体（Controller Dual Mode）

## 何时调用

- 希望同一个控制器方法既能渲染页面（HTML），也能作为接口返回 JSON。
- 需要让现有页面接口在移动端/脚本调用时返回结构化数据。

## 触发与认证

- 触发：请求头 `Accept` 包含 `application/json`。
- 认证：Header 传 `Authorization: Bearer <tokenContent>`。

## 实现要点

- 控制器方法必须调用 `$this->fetch()`，不要使用 `View::fetch()`。
- 无论使用 `$this->assign()` 还是 `View::assign()`，其数据都会被转换为 JSON 返回。
- 若不希望某个 assign 字段出现在 JSON 中，可使用：

```php
$this->assign('name', 'value', -1);
```

## 特殊行为

- `index` 方法 GET 默认返回分页数据；如果需要返回 assign 数据，URL 增加参数 `get_page_data=1`。
- 仅在控制器模式（Controller Mode）生效；路由模式（Route Mode）不生效。