SunAdmin 开发文档

主题

🧰 公共函数与工具 ​

本页记录项目中常用的全局函数、核心工具类和使用边界。

🎯 本页目标 ​

读完本章节后，应能：

  • 知道项目里哪些全局辅助函数可以直接使用，避免重复造轮子。
  • 区分这些函数适合写在 Controller、Service 还是 Dao。
  • 找到响应、配置、字典、缓存、媒体 URL 等常用能力的入口。

📣 全局响应函数 ​

定义：

text
app/Support/helpers.php

成功响应：

php
success(mixed $data = null, string $message = '', int $code = 200): JsonResponse

失败响应：

php
error(string $message = '', int $code = 400, int $status = 200, mixed $data = null): JsonResponse

返回结构统一为：

json
{
  "code": 200,
  "message": "",
  "data": {}
}

📃 分页函数 ​

php
getPageConfig(array $params = [], bool $isRelieve = true, ?int $defaultLimit = null): array

参数来源优先级：

  1. 显式传入 $params。
  2. 当前请求 query/body。
  3. config('sunadmin.list.page_size')。

字段：

字段说明
page_no当前页
page_size每页数量

特殊规则：

  • page_no=0 表示解除分页。
  • page_size 超过 page_size_max 时会被限制。
  • 默认最大值在 config/sunadmin.php 中配置为 200。

🌳 数组转树 ​

php
array_to_tree(array $data, string $subKeyName = 'children', string $idName = 'id', string $parentIdName = 'pid', int|string $parentId = 0): array

适合菜单、部门、分类等简单树结构。

📥 请求取值工具 ​

Trait：

text
app/Core/Http/Concerns/InteractsWithPickedInput.php

方法：

方法说明
payload()GET/HEAD 取 query，其他方法取 body
payloadParam($name, $default)从 payload 读取字段
pick($params, $suffix = false)按白名单提取字段并 trim 字符串

FormRequest 的场景校验依赖 pick()。

🔗 URL 工具 ​

text
app/Support/Url/AppUrlResolver.php

方法：

方法说明
baseUrl()优先从当前请求推断域名，兜底 config('app.url')
to($path)拼接完整 URL
host()当前 host
origin($scheme)生成指定协议 origin

🧾 JSON 工具 ​

text
app/Core/Support/JsonField.php

方法：

方法说明
decodeArray()安全解码数组，兼容转义 JSON
encodeNullable()空值返回 null，否则编码数组
encodeArray()使用中文和斜杠不转义的 JSON 编码

🔖 缓存版本工具 ​

text
app/Support/Cache/CacheVersionManager.php

方法：

方法说明
version($name)获取版本，首次读取初始化为 1
bump($name)递增版本，用于缓存失效

当前版本名：

名称用途
public_config公开配置
decorate_page装修页
language_message语言包

💉 注入属性 ​

项目使用 #[Inject] 配合 PropertyInjector 注入 Action、Service、Dao。

示例：

php
#[Inject]
protected UserAuthAction $userAuthAction;

建议：

  • Controller / Action 中可使用属性注入减少构造器噪音。
  • 对必须显式传参的服务，仍可保留构造器注入。
  • 注入属性不要在声明处初始化。

注入机制由 app/Core/Providers/InjectServiceProvider.php 注册，它将 PropertyInjector 注册为单例并挂钩 Laravel 的 resolving 事件，对 App\ 和 Modules\ 命名空间下的对象自动扫描 #[Inject] 属性。

🕐 时间工具 ​

text
app/Support/Time/TimeRange.php

TimeRange 提供 HH:MM 时间字符串的比较和时间段去重能力。

方法说明
toMinutes(string $time)将 HH:MM 转为总分钟数
isValid(string $start, string $end)判断起止时间是否有效（非空且 start < end）
isExpiredToday($date, string $start, $now)判断当天时间段是否已过期
uniqueSlots(array $slots, ...)按 start-end 去重并按起始时间排序

📋 列表值归一化 ​

text
app/Support/Value/ListValueNormalizer.php

将混合输入（数组、JSON 字符串、逗号分隔字符串）统一归一化为数组。

方法说明
toList(mixed $value)统一输出数组：null/空串返回 []，JSON 自动解码，逗号（中英文）自动分割
toStringList(mixed $value, array $keys)在 toList 基础上，从每个元素中提取字符串（支持关联数组按 name/label 取值）

🗂️ 其他 Support 工具 ​

app/Support/ 下还有以下工具，按子目录组织：

目录文件说明
File/MediaUrlTransformer媒体 URL 相对路径与完整 URL 互转，被 HasMediaUrlAttributes 调用
File/MediaFieldFormatter媒体字段格式化，处理富文本中的资源 URL
File/PublicStorageLinkstorage:link 的程序化封装
Cache/CacheVersionManager缓存版本号管理，用于公开配置、装修页、语言包的缓存失效
Install/InstallWizardService安装向导业务逻辑
Install/AppKeyBootstrapper应用密钥初始化
Modules/ModuleManager模块启用/禁用/卸载状态管理
Modules/ModuleResourcePublisher模块资源发布（前端页面、uni-app 源码）
Modules/ModuleRuntimeBuilder模块运行包构建
Language/FrontendI18nScanner前端代码国际化文案扫描
Language/ModuleTranslationInstaller模块语言包安装
Openapi/OpenapiExporterOpenAPI 文档导出
Openapi/RuleTranslatorLaravel 验证规则转 OpenAPI schema
Openapi/TagResolverOpenAPI 标签解析
Url/AppUrlResolver应用 URL 解析（已在上方介绍）
—ModuleRegistry模块注册表，扫描模块目录、路由、Service Provider
—Version版本号读取（与 composer.json 同步）

这些工具多为框架内部使用，业务开发通常不需要直接调用。模块开发、安装器扩展、OpenAPI 集成等场景可按需引用。