TP5自定义函数如何写注释-ThinkPHP-PHP中文网

tp5自定义函数注释须写在common.php中并严格使用phpdoc格式：顶格/**开头、紧贴函数、完整@param/@return/@throws，返回类型必须为\think\response等实际对象类型，不可写array或遗漏。

tp5自定义函数如何写注释

TP5自定义函数注释要加在 `common.php` 里，且必须用 PHPDoc 格式

TP5 的 common.php 是全局函数文件，但框架本身不解析或校验其中的注释——注释只对 IDE、静态分析工具（如 PHPStan）、以及后续可能接入的文档生成器（如 apidoc）起作用。所以你写不写、怎么写，不影响运行，但影响协作和可维护性。

关键点是：必须用标准 PHPDoc 块注释（/** */），不能用单行 // 或多行 /* */，否则 PHPStorm、VS Code 的参数提示、跳转、类型推导基本失效。

/** 必须顶格，紧贴函数声明上方，中间不能空行
每个 @param 要写清类型和变量名，比如 @param string $name，别写 @param $name（类型丢失）
@return 后必须跟类型，void / array / int / \think\Response 等，不能留空
如果函数可能抛出异常，加上 @throws \Exception（尤其封装了数据库操作或 HTTP 请求时）

示例（放在 application/common.php 中）：

/**
 * 统一 API 响应输出函数
 * @param int $status 业务状态码，1 表示成功
 * @param string $message 提示信息
 * @param array $data 返回的数据体，可为空数组
 * @param int $httpCode HTTP 状态码，默认 200
 * @return \think\Response
 * @throws \think\Exception
 */
function show($status, $message, $data = [], $httpCode = 200)
{
    $data = ['status' => $status, 'message' => $message, 'data' => $data];
    return json($data, $httpCode);
}

`show()` 这类函数的注释里，`@return` 类型必须写 `\think\Response`

很多人写成 @return array 或漏掉，结果在控制器里调用 return show(...) 时，IDE 会误判返回值类型，导致后续链式调用（比如想加 header）没提示，甚至类型检查报错。

原因很直接：json() 是 TP5 的助手函数，它内部返回的是 \think\Response 实例，不是原始数组。框架靠这个对象完成 Content-Type 设置、状态码发送、异常拦截等动作。

写 @return array → IDE 认为你返回的是数组，->header() 这类方法就没了提示
不写 @return → PHPStan 直接报 “Missing return type” 错误
写 @return \think\Response → 所有响应链路方法（header()、withCookie()、contentType()）都能被识别

顺带提醒：\think\Response 在 TP5.1+ 中路径没变，但如果你项目是 TP5.0，类名是 \think\response\Json，注释里就得对应写清楚。

CuspAI

CuspAI是一款AI工具，剑桥大学推出的材料学专业AI搜索工具。

下载

注释里别硬编码路径或版本号，用相对命名空间

你在 common.php 里写的函数，很可能被模型、事件、命令行脚本等多处调用。如果注释里出现类似 @see application/api/controller/Test.php 这种绝对路径，一旦目录结构调整（比如从 api 拆成 v1、v2），所有注释都得手动改，且 IDE 不会帮你定位。

更稳妥的做法是用逻辑引用：

用 @see show() 指向同文件内其他函数
用 @see \app\common\lib\exception\ApiHandleException 指向具体类（注意反斜杠开头）
需要说明使用场景时，写“常用于 API 控制器的统一输出”，而不是“见 Test.php 第 12 行”

另外，@deprecated 标记比删函数更实用。比如旧版 apiReturn() 已被 show() 替代，就在原函数注释头加一行：@deprecated use show() instead，调用时 IDE 会划删除线并提示替代方案。

别依赖 DocBlockr 自动补全来写函数注释

Sublime 的 DocBlockr 插件对类方法、控制器 action 注释支持较好，但它识别不了 common.php 里的自由函数——因为没上下文（没 class、没 namespace、没 visibility）。你敲 /** 回车，它大概率生成空模板或错误参数占位符（比如把 $data = [] 解析成 @param [type] $data = []）。

所以这类函数注释，老老实实手写，或用 IDE 内置模板（PHPStorm 输入 /** + 回车自动展开，VS Code 安装 PHP DocBlocker 插件后也支持）。重点检查三处：

参数个数是否和函数签名一致（特别是默认值参数要不要写 @param）
@return 类型是否与实际返回对象匹配（再次强调：不是 json() 的输入数组，而是它的返回值）
有没有漏掉可能抛出的异常类型（比如 show() 本身不 throw，但如果你封装了 Db::transaction()，就要加 @throws \think\db\exception\DataNotFoundException）

最易忽略的一点：TP5 的 common.php 是被所有请求共享加载的，里面函数的注释一旦写错类型，会影响整个项目的静态分析结果。宁可少写，也不要写错。