签入版本

EasyGoAdmin_Gin_NaiveVue/zh/appendix/functions.md

@@ -1,66 +1,100 @@
-# D. 公共函数速查
+# D. Utility 函数速查
 
-:::tip 概述
-以下函数定义在 `app/common.php` 中，可在任何地方直接调用。
+:::tip 说明
+`utility/` 13 个基础包的常用入口速查。全部包无业务语义、不 import internal。
 :::
 
-## 字符串 / 加密
+## apperr
 
-| 函数 | 说明 | 签名 |
-|------|------|------|
-| `random_string($length)` | 生成随机字符串 | `string random_string(int $length = 16)` |
-| `encrypt_password($password, $salt)` | 密码加密（bcrypt） | `array encrypt_password(string $password, ?string $salt = null)` |
-| `verify_password($password, $hash, $salt)` | 验证密码 | `bool verify_password(string $password, string $encryptPassword, string $salt)` |
+| API | 说明 |
+|---|---|
+| apperr.New(code, msg) | 构造业务错误 |
+| apperr.Newf(code, format, args...) | 格式化业务错误 |
+| .Code() | 取码（response 映射用） |
 
-## 文件处理
+业务代码经 consts 别名引用（CodeXxx 哨兵）。
 
-| 函数 | 说明 | 签名 |
-|------|------|------|
-| `upload_file($formName, $type)` | 上传文件到临时目录 | `array upload_file(string $formName = 'file', string $type = 'file')` |
-| `save_file($fileUrl, $saveDir)` | 临时文件迁移到正式目录 | `string\|false save_file(string $fileUrl, string $saveDir = '')` |
-| `save_content(&$content, $saveDir)` | 处理富文本中的媒体文件 | `bool save_content(string &$content, string $saveDir = 'article')` |
-| `get_file_url($path)` | 相对路径转完整 URL | `string get_file_url(string $path)` |
-| `create_file_path($saveDir, $ext)` | 生成文件存储路径 | `string create_file_path(string $saveDir = '', string $ext = '')` |
-| `save_remote_file($url, $saveDir)` | 保存远程文件 | `string\|false save_remote_file(string $url, string $saveDir = '')` |
-| `detect_image_ext($content)` | 根据内容检测图片后缀 | `?string detect_image_ext(string $content)` |
+## cache
 
-## 驼峰 / 下划线转换
+| API | 说明 |
+|---|---|
+| Init / Close / InMemory | 生命周期与模式查询 |
+| Set / Get / Del / Exists | 基础读写（TTL 秒） |
+| SetNX | 不存在才写（锁） |
+| Incr | 计数（限流） |
+| ZAdd/ZRem/ZRangeByScore/ZCard/ZRemRangeByScore | 有序集合（在线会话） |
+| PING / Info / DBSize | Redis 原始（监控） |
 
-| 函数 | 说明 | 签名 |
-|------|------|------|
-| `snake_to_camel($str)` | 下划线转驼峰 | `string snake_to_camel(string $str)` |
-| `camel_to_snake($str)` | 驼峰转下划线 | `string camel_to_snake(string $str)` |
-| `array_snake_to_camel($data)` | 数组键名下划线转驼峰（递归） | `array array_snake_to_camel(array $data)` |
-| `array_camel_to_snake($data, $except)` | 数组键名驼峰转下划线（递归） | `array array_camel_to_snake(array $data, array $except = [])` |
-| `is_camel_convert_enabled()` | 是否开启转换 | `bool is_camel_convert_enabled()` |
+## captcha
 
-## 工具函数
+| API | 说明 |
+|---|---|
+| Generate(ctx) | 返回 (key, dataURL) |
+| Verify(ctx, key, code) | 校验（一码一用） |
 
-| 函数 | 说明 | 签名 |
-|------|------|------|
-| `get_client_ip()` | 获取客户端 IP | `string get_client_ip()` |
-| `format_page_params($params)` | 格式化分页参数 | `array format_page_params(array $params)` |
+## config
 
-## 使用示例
+| API | 说明 |
+|---|---|
+| config.String(key, def) | 字符串 |
+| config.Bool(key, def) | 布尔 |
+| （数值型同族） | 配置读取统一入口 |
 
-```php
-// 生成随机字符串
-$str = random_string(32);
+## crypto
 
-// 密码加密
-$result = encrypt_password('123456');
-// ['password' => '$2y$12$...', 'salt' => 'xK7pMn3qRt']
+| API | 说明 |
+|---|---|
+| GenerateSalt() | 随机盐 |
+| HashPassword(password, salt) | bcrypt 哈希 |
+| VerifyPassword(hashed, password, salt) | 恒时比对 |
+| IsBcrypt(hashed) | 格式识别 |
 
-// 验证密码
-$ok = verify_password('123456', $user->password, $user->salt);
+## excel
 
-// 文件上传
-$result = upload_file('avatar', 'image');
-if (isset($result['error'])) {
-    return Result::fail($result['error']);
-}
+| API | 说明 |
+|---|---|
+| ReadSheet(file) | (headers, rows, err)，剥表头跳空行 |
+| WriteSheet(dir, baseName, headers, rows) | 写 xlsx，返回 fileName/filePath |
 
-// 驼峰转换
-camel_to_snake('createTime');    // 'create_time'
-snake_to_camel('create_time');   // 'createTime'
-```
+## ip2region
+
+IP → 归属地（消费 xdb 数据库文件），登录/操作日志采集用。
+
+## jwt
+
+| API | 说明 |
+|---|---|
+| Sign(ctx, tokenType, userID, tenantID, username, realname) | 签发双令牌 |
+| Parse(ctx, tokenStr) | 解析校验（Claims） |
+| ExpireDuration(ctx, tokenType) | 有效期 |
+
+## logger
+
+结构化 zap：Infof/Warnf/Errorf 等，支持 ctx 追踪字段（trace_id 自动关联）。
+
+## response
+
+| API | 说明 |
+|---|---|
+| Ok / OkMsg / Page | 成功信封 |
+| Fail / FailCode | 失败信封（401 原码透出） |
+| Write / WriteWithCode | 写出并记录（中间件读取） |
+| DeniedReason / GetDeniedReason | 拒绝原因传递 |
+
+## upload
+
+| API | 说明 |
+|---|---|
+| SaveTemp | 两段式第一段 |
+| SaveFromTemp / SaveFromTempMulti | 转正 |
+| GetFileUrl | 相对路径 → 访问 URL |
+| SafeJoin | 路径穿越防护 |
+| BaseDir / TempBaseDir / GetAccessBase | 目录基址 |
+
+## ua / validator
+
+ua：User-Agent 解析（OS/浏览器）。validator：binding 标签校验引擎（router 绑定层调用）。
+
+## 相关
+
+- [4.7 基座与公共体系](/zh/architecture/base-system.html)