ThxFly (Shooting Fly)

开源 BI 工具 - Metabase 实战指南

ThxFly — Mon, 02 Mar 2026 14:45:19 +0800

Metabase 实战指南

Metabase 是一个开源的 BI 工具，特点是上手简单，界面友好，使用符合直觉。下面讲讲怎么用它搭建数据看板。

整体流程一览

连上数据库 —— 把 Metabase 跟你现有的数据源打通
建集合 —— 相当于文件夹，把东西归类放好
建模型（推荐）—— 把常用的表封装成模型，方便非技术人员理解和使用
做指标 —— 在集合里创建「问题」，也就是你要查询的数据
搭看板 —— 把指标组装成一个可交互的监控面板
置顶发布 —— 让重要的看板更容易被找到

第一步：连接数据库

首先得让 Metabase 认识你的数据。

点右上角 齿轮图标 → 管理设置
左侧选 数据库 → 添加数据库
填写连接信息：
- 显示名称：起个好认的名字，比如「生产数据库」
- 数据库类型：MySQL、PostgreSQL、ClickHouse、StarRocks 等
- Host、Port、数据库名、用户名、密码：按实际情况填写
建议打开两个选项：
- ✅ Sync schema：自动同步表结构
- ✅ Cache field values：缓存字段值，筛选器加载会快很多
点保存，状态显示绿色即表示连接成功

第二步：创建集合

集合相当于文件夹，可以帮你把不同业务的数据分门别类。

点左上角 「+ 新建」 → 「集合」
命名建议：
- 一级目录按业务域划分，如「交易」「用户」「财务」
- 二级目录按主题划分，如「交易/日常监控」「交易/活动复盘」
想建子目录？先进去该集合，再按同样方法创建即可
还可以设置权限——点右上角 「...」 → 「编辑集合」 即可管理谁能看、谁能改

第三步：创建模型（推荐）

这是 Metabase 区别于 Superset 的特色概念。模型 (Model) 是对一张或多张表的封装，比普通表更「聪明」：

可以添加描述和元数据，让非技术人员也能看懂
可以在模型层面设置缓存策略
创建指标时，模型会出现在更显眼的位置
可以简单理解为 SQL 里视图的概念

什么时候用模型？

这张表会被频繁复用
字段名过于技术化，需要给业务人员解释（如 stts_cd → 「订单状态」）
想统一管理某类数据的刷新策略

怎么创建模型？

进入目标集合 → 「+ 新建」 → 「模型」
选择数据源（一张表，或写一个 SQL 定义虚拟表）
添加元数据：
- 显示名称：业务友好的名字
- 描述：这张表是干什么用的
- 字段标签：把技术字段名改成业务名（如 ord_stts 改成「订单状态」）
- 字段类型：告诉 Metabase 哪个是日期、哪个是金额
- 过滤/分组：标记哪些字段适合筛选、哪些适合分组
保存

把常用的表（如订单表、用户表）做成模型，后续业务人员用起来会顺手很多。如需修改，点右上角 「...」 → 「编辑模型详情」 即可。

第四步：创建指标（问题）

在 Metabase 里，你创建的查询都叫「问题」(Question)，也就是我们说的「指标」。

先进到目标集合，点 「+ 新建」 → 「问题」。

方式 A：图形化拖拽

选一张表，或者直接选一个模型（如果有的话）
配置数据：点击 「+ 筛选」 添加条件，如「状态 = 已支付」；点击 「+ 汇总」 选择计算方式，如计数、求和、平均值；按需要的维度分组，如「创建时间 - 天」
配置可视化：右上角切换图表类型（折线图、柱状图、饼图、数字卡等）
点 「可视化」 预览效果，点 「保存」，记得选对集合，名字起清楚，如「每日支付订单量」

方式 B：写 SQL

点 「+ 新建」 → 「SQL 查询」
选择数据库（第一步配置的那个）
写你的 SQL。如果需要动态参数，用 {{变量名}} 语法： sql SELECT COUNT(*) AS total_users FROM users WHERE {{created_at_filter}}
右侧边栏可以配置变量类型：文本、数值、日期、布尔值……如果是字段筛选器，还需映射到具体字段
写完点 「运行」（或 Cmd + Enter），点 「保存」，选好集合和名字
然后同方式 A 配置图表类型

不管用哪种方式，保存好的「问题」就是可复用的指标了，后面直接拖到看板里就能用。

第五步：搭建仪表板（看板）

把指标组合在一起，配上过滤条件，就是一个可以看的监控大盘了。

创建看板

进入目标集合 → 「+ 新建」 → 「仪表板」，起个名字，如「交易核心监控大盘」。

添加指标

点看板右上角的 ➕ 进入编辑模式
勾选想放的指标

调整布局

拖拽：按住卡片标题拖到想放的位置
缩放：拖动右下角调整大小，支持跨列
排版建议：关键数字放顶部，趋势图放中间，明细表放底部

配置过滤条件（重点！）

这是让看板活起来的关键。

编辑模式下，点顶部工具栏的 漏斗图标
添加一个全局过滤器：
- 选择类型：如时间范围、下拉列表、搜索框
- 命名：如「业务日期」「城市」
把过滤器跟卡片关联起来：
- 点过滤器下方的箭头 → 「编辑关联」
- 把全局的「时间」映射到卡片 A 的 created_at、卡片 B 的 paid_at
- 注意：SQL 创建的卡片需要 SQL 中包含 {{变量名}} 才能生效
如果某张卡只需独立过滤，不跟全局联动，可在卡片的 「...」 → 「编辑」 中单独设置

完成

点右下角 「完成编辑」 退出编辑模式。

第六步：置顶与分享

辛辛苦苦做的看板，可别让它淹没在列表里。

置顶

在看板页面点右上角 「...」
选择 「置顶」
选择位置：
- 集合顶部：仅在当前集合内置顶
- 全局置顶：所有人登录后首页都能看到（需管理员权限）

验证

回到首页或集合页，确认看板出现在最上方的「已置顶」区域。

分享（可选）

点 「分享按钮」，可以生成公开链接、导出 PDF 或设置邮件订阅。

真实示例

常用快捷键

全局

操作	快捷键
创建问题	`c` > `q`
创建 SQL 查询	`c` > `n`
创建仪表板	`c` > `d`
创建集合	`c` > `f`
创建模型	`c` > `m`
创建指标 (Metric)	`c` > `k`
浏览数据库	`g` > `d`
浏览模型	`g` > `m`
浏览指标	`g` > `k`
打开个人空间	`g` > `p`
打开回收站	`g` > `t`
切换侧边栏	`[`
进入管理后台	`g` > `a`
进入用户设置	`g` > `u`
返回首页	`g` > `h`

仪表板

操作	快捷键
进入编辑模式	`e`
添加过滤器	`f`
添加问题侧边栏	`a`
添加图形化问题	`q`
添加 SQL 问题	`n`
保存仪表板	`s`
切换仪表板信息	`]`
收藏/书签看板	`o`
切换 Tab	`1`, `2`, `3`...
删除仪表板	`Ctrl/Cmd` + `Backspace`

问题/查询

操作	快捷键
切换到编辑器	`e`
打开筛选器下拉	`f`
打开汇总侧边栏	`s`
收藏/书签问题	`o`
打开问题详情	`]`
刷新数据	`r`
切换可视化类型	`v`
切换可视化设置	`y`
切换图表类型菜单	`t`
运行查询	`Cmd + Enter`（Mac） / `Ctrl + Enter`（Windows）
保存	`Cmd + S`（Mac） / `Ctrl + S`（Windows）
删除问题	`Ctrl/Cmd` + `Backspace`

管理员

操作	快捷键
切换管理后台 Tab	`1`, `2`, `3`...

开源版 vs 商业版

根据官方定价页面的信息整理：

开源版（免费）

类别	功能	说明
数据查询	✅ Query Builder（图形化查询）	可视化拖拽构建查询
	✅ SQL Editor	支持原生 SQL
	✅ Models（模型）	封装表结构，添加元数据
	✅ 基础缓存	Query and model caching
	❌ Metabot AI	需付费 ($100/月起)
可视化	✅ 无限图表/看板	折线图、柱状图、饼图、数字卡等
	✅ 看板过滤	支持全局过滤
	✅ 交互式钻取	点击穿透查看详情
	✅ X-Ray 自动报告	自动生成数据概览
	⚠️ 邮件订阅	需配置 SMTP，带 Metabase 水印
	⚠️ Slack 订阅	带 Metabase 水印
	⚠️ PDF 导出	带 Metabase 水印
	✅ 公开链接分享
权限管理	✅ 集合权限	按集合分配查看/编辑权限
	❌ 行级/列级权限	需 Pro 版
	❌ 沙箱 (Sandbox)	需 Pro 版
认证	✅ Google Auth
	⚠️ LDAP	仅支持基础认证（登录）
	❌ SAML / SSO	需 Pro 版
	❌ JWT	需 Pro 版
	❌ SCIM 自动账号同步	需 Pro 版
嵌入	⚠️ Guest Embeds	仅基础嵌入，带 "Powered by Metabase" 水印
	❌ White-label（去水印）	需 Pro 版
	❌ 交互式嵌入 (Full-app)	需 Pro 版
组织	✅ 集合/个人空间
	❌ 官方集合 (Official Collections)	需 Pro 版
	❌ 审核问题 (Moderated questions)	需 Pro 版
	❌ 验证模型 (Verified models)	需 Pro 版
数据源	✅ 20+ 数据库连接器	MySQL、PostgreSQL、ClickHouse 等
	✅ CSV 上传
部署	✅ 自托管	需自己维护服务器
	❌ 多区域托管	需 Starter 版
	❌ Serialization（配置导出/导入）	需 Pro 版
支持	社区论坛	discourse.metabase.com
许可证	AGPL	商用需注意开源协议

商业版 (Starter / Pro / Enterprise)

版本	价格	定位
Starter	$100/月 + $6/月/人	全托管云版，含官方支持
Pro	$575/月 + $12/月/人	细粒度权限、White-label、嵌入、Usage Analytics
Enterprise	$20,000/年起	大客户专属成功工程师、合规需求

小团队用开源版就够用了；想把看板嵌入到自家产品里，需要买商业版。

关于汉化的一个问题

Metabase 自带中文翻译，但有些翻译比较生硬，甚至让人误解。比如：

某些功能名翻译不够准确
某些词过于直译，看不懂

如果你们的 Metabase 启用了中文界面，创建用户时，名字写全名，姓留空。这样在仪表板、问题等处显示的就是完整名字，不会出现「小明李」这类情况。

热心的小伙伴可以创建 PR 给到官方，帮忙优化翻译。

其他

我也用过 Superset，对比下来 Metabase 用起来更舒服，很多操作比较符合直觉，看起来是个更不错的 BI 工具。

Rails 技术实战之 AI 找货小助手设计

ThxFly — Tue, 10 Feb 2026 19:16:13 +0800

AI 找货助手技术实现指南

最近阿里云千问的"点奶茶"技能很火，碾压了微信红包的 AI 玩法。这波 AI 热潮下，我们在 APP 里也做了一个 AI 找货功能。

用户搜"温润的手镯"，传统搜索只认"温润"和"手镯"两个字。但用户真正想要的是和田玉——因为"温润"是和田玉的特征。

这篇讲讲怎么用向量搜索 + AI 对话，让系统理解用户真正想要什么。淘宝、京东、美团、携程都有类似功能，我们这个还比较粗浅，讲个大概，体验看起来还有待优化，还请包涵。

需求预览

核心概念

概念	说明
Dify	开源 LLM 应用开发平台，我们用它做工作流编排。Dify 部署成独立服务，Rails 后端通过 HTTP API 调用。
SSE	Server-Sent Events，服务器主动推送数据给前端，比 WebSocket 简单，适合这种单向实时推送的场景。
向量搜索	把文本转成 1024 维向量，算向量相似度来找商品。比如"温润的手镯"能匹配到"和田玉手镯"。
KNN	K 最近邻算法，在向量空间里找最相似的 K 个商品。K 越大结果越多，但也越慢。
Embedding	把文本转成向量的过程，语义相近的文本向量也相近。
HNSW	一种高效的向量索引算法，ES 8.x 原生支持，用来加速 KNN 搜索。

一、技术架构总览

1.1 整体架构图

整体流程

用户在前端输入需求 → SSE 建立长连接 → Rails 把请求转给 Dify → Dify 识别意图、提取参数 → Dify 调用 Rails 的搜索接口 → Rails 生成查询向量 → ES 做 KNN 向量搜索 → 结果沿路返回 → 前端展示。

几个关键点

前端和 Rails 之间用 SSE，服务器主动推送，不用轮询。
Dify 是外部服务，Rails 只负责转发和调用搜索接口。
搜索用的是向量搜索，不是传统的关键词匹配。

核心配置

配置项	环境变量	作用
Dify API 地址	`DIFY_API_BASE_URL`	Dify 服务的 URL
Dify API Key	`DIFY_CHATFLOW_API_KEY`	调用工作流的认证密钥

核心接口

接口	路径	谁调用
SSE 对话接口	`POST /api/v1/chat/stream`	前端
商品语义搜索接口	`POST /api/v1/products/ai_search`	Dify 工作流

1.2 商品列表接口

GET /api/v1/products 这个接口支持两种搜索方式：普通搜索（传 q、category_id、price_min/max 等参数），和 ai_search_id 搜索（传之前搜索的 ID，复用搜索参数）。

使用场景是这样的：用户在对话里看到商品列表，想看更多，点"查看更多"按钮，前端把之前的 ai_search_id 传过来，后端直接从数据库捞出之前的搜索参数，做分页查询。

1.3 数据流转

两个关键点

商品向量是上架时生成的，存在 ES 里；查询向量是每次搜索实时生成的。
向量生成失败了怎么办？降级处理，返回空结果或者转关键词搜索。

1.4 技术栈

组件	选型	说明
工作流引擎	Dify	最新版，做 AI 流程编排
LLM	通义千问 qwen-plus-latest	意图理解、参数提取
搜索引擎	Elasticsearch 8.x	商品索引 + KNN 向量搜索
后端框架	Ruby on Rails 8.x	业务逻辑

二、SSE 事件设计

2.1 事件流程图

2.2 事件类型

事件类型	触发时机	作用
`system_message`	连接建立后、stream_end 前	系统提示，比如"正在匹配货品中"，或者错误提示
`message_start`	第一次收到 Dify 的 message	告诉前端准备接收消息
`message`	收到 Dify 的 message	真正推送内容，可能拆成多个片段
`thought`	Dify 节点开始处理	显示"正在处理：xxx"，让用户知道进度
`message_end`	收到 Dify 的 message_end	一条消息发送完成
`stream_end`	整个流程结束	前端可以关闭连接了

msg_type 的取值

message_start 和 message 的 msg_type：

Dify 返回 PRODUCT_CARD → product_card（商品卡片）
Dify 返回 CLARIFY_CARD → clarify_card（追问卡片）
Dify 返回 TEXT → text（普通文本）
其他情况默认 text，结构化内容可能是 blocks

system_message 的 msg_type：

show_thinking：显示思考过程
hide_thinking：隐藏思考过程
text：普通系统文本
retry：可重试的错误

2.3 事件数据格式

message_start

{
  "event": "message_start",
  "data": {
    "msg_id": "uuid",
    "msg_type": "text",
    "role": "assistant",
    "task_id": "uuid"
  }
}

message

{
  "event": "message",
  "data": {
    "msg_id": "uuid",
    "content": "这是消息内容",
    "task_id": "uuid"
  }
}

message_end

{
  "event": "message_end",
  "data": {
    "msg_id": "uuid",
    "status": "success",
    "usage": {
      "prompt_tokens": 100,
      "completion_tokens": 50,
      "total_tokens": 150
    }
  }
}

stream_end

{
  "event": "stream_end",
  "data": {
    "conversation_id": "uuid",
    "status": "success"
  }
}

system_message

{
  "event": "system_message",
  "data": {
    "id": "uuid",
    "msg_type": "text",
    "role": "system",
    "content": "正在匹配货品中",
    "user_message_id": 123
  }
}

thought

{
  "event": "thought",
  "data": {
    "msg_id": "uuid",
    "content": "正在处理：属性提取",
    "task_id": "uuid"
  }
}

2.4 事件顺序和处理规范

标准顺序

连接建立后，先发 system_message（show_thinking）告诉用户"正在匹配"
收到 Dify 的 message，第一次发 message_start，然后发 message（可能多次）
收到 node_started 时可以发 thought
收到 message_end 时发 message_end
有系统消息（错误或提示）发 system_message
最后发 stream_end

错误处理

错误不走单独的 error 事件，统一用 system_message
msg_type 是 retry 表示可重试的错误
不管成功失败，最后都会发 stream_end

前端注意事项

message 是流式的，前端要累积内容直到收到 message_end
根据 msg_type 决定怎么渲染
收到 stream_end 就关闭连接

三、Dify 对话流设计详解

3.1 工作流核心结构

我们用 Dify 的节点式编排来做对话流，核心节点如下：

节点类型	作用
Start	接收用户输入和认证信息
Question Classifier	意图识别，分成 4 种意图
LLM	属性提取，把用户输入转成结构化参数
If-Else	判断要不要追问用户
LLM	生成追问话术和选项按钮
HTTP Request	调用后端搜索接口
Code	结果合并，各分支互斥，只返回其中一个结果

工作流里的变量：环境变量 HTTP_DOMAIN 存 API 域名。

3.2 Start 节点

起点，接收前端传来的变量：

变量	类型	说明
intent	string	用户意图标识
authorization	string	Bearer Token
version_date	string	版本日期（可选）

3.3 意图识别

用 Dify 的 Question Classifier 节点，把用户请求分成 4 类：

分类 ID	名称	例子
1	找货意图	"找翡翠手镯"、"想买和田玉"
2	知识问答	"怎么鉴别翡翠 A 货"、"如何保养和田玉"
3	App 问答	"怎么注册账号"、"如何发布商品"
4	闲聊	"你好"、"谢谢"、"再见"、"今天天气怎么样"

模型配置：通义千问 qwen-plus-latest，Temperature 设 0.3 保证分类稳定，对话记忆保留最近 10 轮。

3.4 属性提取

从用户输入里提取搜索参数，用 LLM 节点，模型也是通义千问，Temperature 0.3。

q 字段（核心搜索描述）

要包含明确的商品品类词
50-100 字的自然语言描述
有些默认规则：用户说"玉石"没具体说是和田玉还是翡翠，默认当和田玉处理；说"高货"默认当翡翠处理。

价格范围

price_min 只有满足"品类 + 高价值信号 + 高价值形态 + 无瑕疵"时才推断。比如用户说"高品质玻璃种翡翠手镯，无纹无裂"，才可能推断最低价。

price_max 按用户字面描述来，用户说"5000 元左右"就设 5000。

分类映射

1=>翡翠，2=>玉石，3=>钻石，4=>彩宝，39=>书画，40=>黄金，107=>黄金饰品，109=>文玩古玩，110=>钱币邮票

输出字段

字段	类型	必填	说明
q	string	是	核心搜索描述
price_min/max	number/null	否	价格范围（元）
category_id	number/null	否	商品分类 ID
inner_circle_size_min/max	number/null	否	圈口尺寸（mm）
heat_min/max	number/null	否	参与热度范围
is_uncertain	boolean	否	是否模糊需追问
has_discount	boolean	否	是否要优惠商品
negative_filters	array[string]	否	排除关键词

3.5 条件判断

检查 is_uncertain 字段，true 就进入追问分支，false 直接搜索。

触发追问的例子

"想买个手镯" → 缺少价格、材质，追问
"5000 元的" → 缺少商品类型，追问
"翡翠手镯，5000-8000 元" → 信息完整，直接搜

3.6 生成追问

当需要追问时，用 LLM 生成话术和选项。Temperature 设 0.7 高一点，让回答更有创造性。

生成规则：message 字段要共情 + 归因 + 引导，suggested_questions 至少 3 个肯定式选项。

{
  "message": "追问话术",
  "suggested_questions": [
    { "title": "问题标题", "intent": "find_item" }
  ]
}

3.7 HTTP 请求节点

真正调用 Rails 搜索接口的地方：

POST 请求
URL：{{#env.HTTP_DOMAIN#}}/api/v1/products/ai_search
请求头带 X-Authorization（从 Start 节点取）

超时和重试：连接/读取/写入都设 10 秒，失败自动重试 1 次。

3.8 结果合并

根据条件判断走不同的分支，各分支互斥，只返回其中一个：追问分支返回追问话术，搜索分支返回商品列表结果，无结果时返回默认话术。

四、向量搜索技术详解

4.1 为什么用向量搜索

传统搜索的局限：

搜索方式	问题
关键词搜索	无法理解语义，"温润的手镯"匹配不到和田玉
短语匹配	要求太精确，用户不会打完整短语
布尔搜索	AND/OR/NOT 组合太复杂，用户不会用

向量搜索能理解语义：

搜什么	关键词搜索	向量搜索
"温润的手镯"	匹配含"温润"和"手镯"的商品	匹配和田玉手镯
"高货"	匹配含"高货"的商品	匹配翡翠高品
"送妈妈的礼物"	几乎没结果	匹配适合送长辈的手镯

4.2 向量搜索原理

流程：文本 → Embedding 模型 → 1024 维向量 → KNN 搜索 → 返回结果。

步骤：1) 把用户输入转成向量；2) 在 ES 里用余弦相似度找最相似的 20 个商品；3) 用 min_score 阈值过滤。

4.3 EmbeddingService 实现

我们用阿里云百炼的 Embedding 接口。一次请求把文本转成 1024 维向量，耗时大概 100-200ms。

缓存策略：相同文本 10 分钟内重复查询直接返回缓存。

错误处理：向量生成失败了返回空数组，后面的 ES 查询就不做了，避免浪费资源。

vector = EmbeddingService.encode("翡翠手镯，种水细腻，色泽温润")
# => [0.023, -0.156, 0.089, ..., 0.012] (1024个浮点数)

4.4 商品向量同步 Job

商品上架后，AI 总结生成完成时自动触发向量生成。流程：

取商品的 AI 总结（必须是已生成的）
组合文本：商品标题 + AI 总结内容
调用 EmbeddingService 生成 1024 维向量
验证向量维度
同步到 ES 的 ai_summary_vector 字段
标记生成时间 vector_generated_at

注意事项：版本冲突自动重试 3 次，失败了要报警。向量是预先生成的，搜索时直接用，不用实时生成。

4.5 ES KNN 查询构建

核心方法：

方法	作用
`build_ai_knn_search_body`	构建 KNN 查询 Body
`extract_knn_filters`	提取过滤条件（排除关键词、圈口尺寸等）
`apply_filters_to_knn_query`	应用过滤条件

关键参数

k：返回多少条结果。翡翠设 30，玉石 25，钻石和彩宝设 20。翡翠商品多，设大一点有足够候选。
min_score：相似度阈值。翡翠设 0.85，玉石 0.8。翡翠商品描述比较标准化，设高一点不容易跑偏。

核心词加权：如果提取到核心词（如"翡翠"），生成向量时重复 3 次，让这个词权重更高。"翡翠手镯" → "翡翠翡翠翡翠手镯" → 生成向量。

4.6 召回、排序、重排

召回流程

生成查询向量
用 HNSW 在向量空间里找最近的 k 个
应用 knn.filter 过滤条件
计算余弦相似度，过滤低于 min_score 的
返回商品 ID 列表

排序：目前只用 _score（相似度分数）降序，简单的做法，后续可以加其他排序维度。

重排：没有额外的重排逻辑，ES 返回什么顺序就是什么顺序。

4.7 完整 ES KNN 查询示例

{
  "knn": {
    "field": "ai_summary_vector",
    "query_vector": [0.023, -0.156, 0.089, 0.234, -0.067, 0.178, ..., 0.012],
    "k": 20,
    "filter": {
      "bool": {
        "filter": [
          { "term": { "category_id": 1 } },
          { "term": { "status": "onsale" } },
          { "term": { "hide_in_miniprogram": false } },
          { "range": { "confirmed_price": { "gte": 5000, "lte": 7000 } } },
          { "range": { "inner_circle_size": { "gte": 55, "lte": 58 } } },
          { "exists": { "field": "ai_summary_vector" } }
        ],
        "must_not": [
          { "match_phrase": { "goods_description_text": { "query": "镶嵌", "analyzer": "ik_max_word" } } }
        ]
      }
    }
  },
  "min_score": 0.8,
  "from": 0,
  "size": 10,
  "sort": [
    { "_score": { "order": "desc" } },
    { "updated_at": { "order": "desc" } }
  ]
}

说明：过滤条件都在 knn.filter 里处理，在向量搜索阶段就过滤，减少计算量。

五、商品语义搜索模块详解

5.1 AiSearch 数据模型

AiSearch 表记录每次搜索的完整参数，搜索条件用 JSONB 存。为什么要冗余存一份 keywords_text？因为运营同学要统计数据，JSONB 查起来麻烦。每条记录关联 ai_chat_id 和 ai_chat_message_id，方便回溯"这条搜索结果是谁发的"。

主要字段

字段名	类型	说明
msg_id	string	消息 ID（唯一索引）
search_params	jsonb	完整搜索参数
keywords_text	string	搜索关键词文本（冗余字段）
category	string	商品分类（冗余字段）
price_min/max	decimal	价格范围（冗余字段）
ai_chat_id	bigint	关联的对话 ID
ai_chat_message_id	bigint	关联的消息 ID

使用场景：记录搜索参数支持"再次搜索"，通过 ai_search_id 复用参数实现"查看更多"，也支持搜索行为分析和统计。

5.2 API Controller 实现

POST /api/v1/products/ai_search

处理流程

参数校验：q 或 category_id 至少一个不为空
创建 AiSearch 记录，生成 ai_search_id
执行搜索：生成查询向量 → 构建 KNN 查询 → ES 查询
数据组装：从数据库捞商品详情，用 Presenter 格式化
返回结果：带 ai_search_id、total、products

成功返回

{
  "success": true,
  "data": {
    "ai_search_id": "uuid",
    "total": 15,
    "products": [
      { "id": 12345, "title": "翡翠手镯", "price": 6000, ... }
    ]
  }
}

错误返回

{
  "success": false,
  "error": "参数错误：q 或 category_id 不能为空"
}

curl 调用示例

curl -X POST "https://api.example.com/api/v1/products/ai_search" \
  -H "X-Authorization: Bearer token" \
  -H "Content-Type: application/json" \
  -d '{"is_ai_search": true, "q": "翡翠手镯，5000-8000元", "category_id": 1, "price_min": 5000, "price_max": 8000}'

错误处理

错误类型	处理方式
参数校验失败	返回 400，提示具体错误信息
向量生成失败	记录日志，返回空结果
ES 查询失败	返回 500，提示"搜索失败，请稍后重试"

六、KNN 按分类配置

配置表：ai_search_knn_category_config

分类 ID	分类名称	k	min_score
1	翡翠	30	0.85
2	玉石（和田玉等）	25	0.8
3	钻石	20	0.82
4	彩宝	20	0.8

k：返回多少条结果。翡翠商品多，设 30；其他品类设 20-25。

min_score：相似度阈值。翡翠设 0.85 因为商品描述标准化，不容易跑偏；其他品类设 0.8。

调参建议：搜索结果太少就降 min_score 或增 k；结果不相关就提高 min_score。如果某个分类经常没结果，可以把 min_score 降 0.05-0.1。

七、常见问题与故障排查

7.1 SSE 连接问题

现象：SSE 连接建立失败或频繁断开

排查步骤

检查请求头：Accept: text/event-stream
检查 token：X-Authorization: Bearer <token>
检查网络和代理设置
看 Rails 日志里的错误信息

常见原因：token 过期或无效、网络超时（默认 60 秒）、服务器主动关闭连接。

7.2 向量生成失败

现象：搜索返回空结果

排查步骤

检查 Embedding 服务 API 是否可访问
检查 API 密钥是否有效
看 Rails 日志的错误信息
检查缓存是否正常（失败的请求也可能被缓存）

解决：向量失败会降级为返回空结果，检查 Embedding 服务配置和网络，清理缓存后重试。

7.3 Dify 工作流调用失败

现象：调用超时或返回错误

排查步骤

检查 DIFY_API_BASE_URL 环境变量
检查 DIFY_CHATFLOW_API_KEY 是否有效
检查 Dify 服务是否正常
看 Rails 日志的详细错误

常见错误：ConnectionError（连不上 Dify）、ResponseError（Dify 返回错误）、ParseError（响应解析失败）。

7.4 ES 查询慢

现象：查询超时或延迟高

排查步骤

检查 ES 集群状态和负载
检查索引分片和副本配置
检查 k 值是否过大（建议不超过 50）
检查 HNSW 参数

优化：适当降低 k、缩小 knn.filter 范围、检查 ES 集群资源。

7.5 搜索结果不相关

现象：返回的商品和用户需求不匹配

排查步骤

检查 Dify 提取的 q 字段是否正确
检查 ES 里的 ai_summary_vector 是否正常
检查 min_score 阈值是否合适
检查核心词加权是否生效

解决：提高 min_score、检查商品 AI 总结质量、优化属性提取规则。

技术架构总结

┌─────────────────────────────────────────────────────────────
│                    AI 找货助手技术架构                         
├─────────────────────────────────────────────────────────────
│  前端层 → SSE 对话接口 → Dify 工作流 → 商品语义搜索接口       
│                              ↓                               
│                      Elasticsearch KNN 搜索                   
│                              ↓                               
│                      商品向量同步 + 查询向量生成               
├─────────────────────────────────────────────────────────────
│  核心流程：Dify 对话流 → 意图识别 → 属性提取 → 追问 → 搜索     
│  核心技术：SSE 实时推送 + 向量语义搜索 + HNSW 高性能索引       
└─────────────────────────────────────────────────────────────

5 分钟快速入门 AI 辅助编程：基于 OpenCode 与免费版 MiniMax M2.1

ThxFly — Tue, 10 Feb 2026 12:29:31 +0800

基于 OpenCode + 免费版 MiniMax M2.1，手把手带你 5 分钟快速上手 AI 辅助编程。

操作指南

步骤一：安装 opencode 最新版

brew install anomalyco/tap/opencode

步骤二：终端运行 opencode

cd 项目根目录
opencode

步骤三：切换模型

步骤四：终端授权

iterm2 会弹出一些授权警告，正常授权即可。

步骤五：开始 AI 编程

示例：帮我新增一个功能：在列表页右上角支持表结构。

最终预览效果

ps: 花了约 1 个多小时，通过与 OpenCode 交互 10 来轮，才最终实现当前效果。过程中包括：导入数据库、插入管理员账号、修改管理员密码、修复 Bug，以及新增“显示 CREATE SQL”等功能。执行一次较复杂的完整流程，大约需要 4 分钟。正常自然语言询问即可。毕竟是白嫖的模型，偶尔也会遇到需要等待的情况。

把 Mac 变成键盘流神器：Hammerspoon 配置指南（窗口管理 + 应用秒开 + 快捷键自定义）

ThxFly — Fri, 28 Nov 2025 11:20:30 +0800

Hammerspoon 是 macOS 上强大的开源自动化工具，通过 Lua 脚本可以控制窗口、绑定快捷键、切换应用等，大幅提升工作效率。

🔧 安装

方式一：使用 Homebrew（推荐）

brew install --cask hammerspoon

方式二：手动安装

从 GitHub Releases 下载 .zip 文件并解压。解压后移到/Applications

首次配置

授权辅助功能
- 打开 系统设置 > 隐私与安全性 > 辅助功能
- 勾选 Hammerspoon 以允许控制电脑
配置文件位置
- 配置文件位于：~/.hammerspoon/init.lua
- 首次启动会自动生成示例文件

📝 配置示例

编辑配置文件：

vim ~/.hammerspoon/init.lua

1. 安全重载配置

配置重载快捷键，出错时会弹窗提示：

-- 安全重载：出错时弹窗提示
hs.hotkey.bind({"cmd", "ctrl"}, "R", function()
  local success, msg = pcall(hs.reload)
  if not success then
    hs.alert.show("❌ 配置错误:\n" .. tostring(msg))
  else
    hs.alert.show("✅ 配置已重载", 1)
  end
end)

2. 窗口管理

窗口分屏（四象限布局）

-- 窗口分屏函数
local function moveWindowTo(rect)
  return function()
    local win = hs.window.focusedWindow()
    if win then win:move(rect, nil, true) end
  end
end

-- 快捷键绑定
hs.hotkey.bind({"cmd", "ctrl"}, "Up",   moveWindowTo(hs.geometry.rect(0, 0, 1, 0.5)))      -- 上半屏
hs.hotkey.bind({"cmd", "ctrl"}, "Down", moveWindowTo(hs.geometry.rect(0, 0.5, 1, 0.5)))   -- 下半屏
hs.hotkey.bind({"cmd", "ctrl"}, "Left", moveWindowTo(hs.geometry.rect(0, 0, 0.5, 1)))     -- 左半屏
hs.hotkey.bind({"cmd", "ctrl"}, "Right", moveWindowTo(hs.geometry.rect(0.5, 0, 0.5, 1)))  -- 右半屏

多显示器切换

-- 将窗口移到下一显示器，并移动鼠标到窗口中心
hs.hotkey.bind({"cmd", "ctrl"}, "F", function()
  local win = hs.window.focusedWindow()
  if win then
    win:moveToScreen(win:screen():next())
    hs.alert.show("窗口已移至下一屏幕", 1)
    hs.mouse.setAbsolutePosition(win:screen():frame().center)
  end
end)

3. 应用快速切换

使用 Option + 字母 快速切换到常用应用：

-- 浏览器
hs.hotkey.bind({"option"}, "s", function()
  hs.application.launchOrFocus("Safari")
end)

hs.hotkey.bind({"option"}, "g", function()
  hs.application.launchOrFocus("Google Chrome")
end)

-- 开发工具
hs.hotkey.bind({"option"}, "a", function()
  hs.application.launchOrFocus("Apifox")
end)

hs.hotkey.bind({"option"}, "t", function()
  hs.application.launchOrFocus("iTerm")
end)

hs.hotkey.bind({"option"}, "c", function()
  hs.application.launchOrFocus("Cursor")
end)

hs.hotkey.bind({"option"}, "d", function()
  hs.application.launchOrFocus("DBeaver")
end)

-- AI 工具
hs.hotkey.bind({"option"}, "e", function()
  hs.application.launchOrFocus("Qianwen")
end)

-- 社交应用
hs.hotkey.bind({"option"}, "w", function()
  hs.application.launchOrFocus("WeChat")
end)

hs.hotkey.bind({"option"}, "q", function()
  hs.application.launchOrFocus("企业微信")
end)

-- 系统工具
hs.hotkey.bind({"option"}, "p", function()
  hs.application.launchOrFocus("System Settings")
end)

-- 娱乐
hs.hotkey.bind({"option"}, "y", function()
  hs.application.launchOrFocus("NeteaseMusic")
end)

4. 快速打开网页

-- 快速打开 GitHub
hs.hotkey.bind({"cmd", "ctrl"}, "G", function()
  hs.urlevent.openURL("https://github.com")
end)

5. 启动提示

-- 菜单栏显示通知
hs.alert.show("Hammerspoon 已加载！")

🔄 重新加载配置

修改 init.lua 后，有两种方式重新加载：

快捷键：按 Cmd+Ctrl+R（默认快捷键）
菜单栏：点击 Hammerspoon 菜单栏图标 → Reload Config

💡 实用技巧

查找应用名称

如果应用切换不生效，可能是应用名称不正确。在 Hammerspoon 控制台中运行：

hs.application.runningApplications()

或者在终端中运行：

osascript -e 'tell application "System Events" to get name of every process'

常用 API 参考

hs.window.focusedWindow() - 获取当前焦点窗口
hs.application.launchOrFocus(name) - 启动或聚焦应用
hs.alert.show(message, seconds) - 显示提示
hs.hotkey.bind(modifiers, key, fn) - 绑定快捷键

📚 更多资源

官方文档：https://www.hammerspoon.org/docs/index.html
GitHub 仓库：https://github.com/Hammerspoon/hammerspoon
示例配置：https://github.com/Hammerspoon/hammerspoon/wiki/Sample-Configurations

🎯 快速上手

一句话总结：写 Lua 脚本 → 绑定快捷键 → 自动化你的 Mac！

提示：根据个人需求调整快捷键和应用名称，打造专属的自动化工作流。

完整代码示例

-- 安全重载：出错时弹窗提示
hs.hotkey.bind({"cmd", "ctrl"}, "R", function()
  local success, msg = pcall(hs.reload)
  if not success then
    hs.alert.show("❌ 配置错误:\n" .. tostring(msg))
  else
    hs.alert.show("✅ 配置已重载", 1)
  end
end)

-- 切换窗口
local function moveWindowTo(rect)
  return function()
    local win = hs.window.focusedWindow()
    if win then win:move(rect, nil, true) end
  end
end

hs.hotkey.bind({"cmd", "ctrl"}, "Up",   moveWindowTo(hs.geometry.rect(0, 0, 1, 0.5)))
hs.hotkey.bind({"cmd", "ctrl"}, "Down", moveWindowTo(hs.geometry.rect(0, 0.5, 1, 0.5)))
hs.hotkey.bind({"cmd", "ctrl"}, "Left", moveWindowTo(hs.geometry.rect(0, 0, 0.5, 1)))
hs.hotkey.bind({"cmd", "ctrl"}, "Right", moveWindowTo(hs.geometry.rect(0.5, 0, 0.5, 1)))

-- 将窗口移到下一显示器
hs.hotkey.bind({"cmd", "ctrl"}, "F", function()
  local win = hs.window.focusedWindow()
  if win then
    win:moveToScreen(win:screen():next())
    hs.alert.show("窗口已移至下一屏幕", 1)
  end
  local win = hs.window.focusedWindow()
  if win then
    hs.mouse.setAbsolutePosition(win:screen():frame().center)
  end
end)

-- 快速打开 GitHub
hs.hotkey.bind({"cmd", "ctrl"}, "G", function()
  hs.urlevent.openURL("https://github.com")
end)

-- 快捷键: Option+s 切换到 Safari
hs.hotkey.bind({"option"}, "s", function()
    hs.application.launchOrFocus("Safari")
end)

-- 快捷键: Option+g 切换到 Google Chrome
hs.hotkey.bind({"option"}, "g", function()
    hs.application.launchOrFocus("Google Chrome")
end)

-- 快捷键: Option+a 切换到 Apifox
hs.hotkey.bind({"option"}, "a", function()
    hs.application.launchOrFocus("Apifox")
end)

-- 快捷键: Option+t 切换到 iTerm
hs.hotkey.bind({"option"}, "t", function()
    hs.application.launchOrFocus("iTerm")
end)

-- 快捷键: Option+c 切换到 Cursor
hs.hotkey.bind({"option"}, "c", function()
    hs.application.launchOrFocus("Cursor")
end)

-- 快捷键: Option+e 切换到 千问
hs.hotkey.bind({"option"}, "e", function()
    hs.application.launchOrFocus("Qianwen")
end)

-- 快捷键: Option+w 切换到 微信
hs.hotkey.bind({"option"}, "w", function()
    hs.application.launchOrFocus("WeChat")
end)

-- 快捷键: Option+q 切换到 企业微信
hs.hotkey.bind({"option"}, "q", function()
    hs.application.launchOrFocus("企业微信")
end)

-- 快捷键: Option+p 切换到 系统设置
hs.hotkey.bind({"option"}, "p", function()
    hs.application.launchOrFocus("System Settings")
end)

-- 快捷键: Option+f 切换到 Finder
hs.hotkey.bind({"option"}, "f", function()
    hs.application.launchOrFocus("Finder")
end)

-- 快捷键: Option+y 切换到 网易云音乐
hs.hotkey.bind({"option"}, "y", function()
    hs.application.launchOrFocus("NeteaseMusic")
end)

-- 快捷键: Option+d 切换到 DBeaver
hs.hotkey.bind({"option"}, "d", function()
    hs.application.launchOrFocus("DBeaver")
end)

-- 菜单栏显示通知
hs.alert.show("Hammerspoon 已加载！")

过时的 Wiki 可以下掉吧？

ThxFly — Sat, 01 Nov 2025 10:36:37 +0800

Ruby China 的 Wiki 好多都已经过时了，没有与时俱进，管理员可以将他们都删了不，从某种程度，不利于新手使用 Ruby 了.

零成本搭建产品知识库：让产研同事能“问”到原型

ThxFly — Sat, 18 Oct 2025 23:47:53 +0800

🚀 零成本搭个产品知识库：让同事直接“问”出原型

一个好的知识库，不是存了多少文档，而是大家愿不愿意用、能不能快速找到答案。

作者：Shootingfly
适用场景：中小团队、用 Axure 做原型、企业微信办公
关键词：知识库、Axure、PDF、企业微信、智能机器人

你有没有遇到过这些情况？

❓ “这个按钮点完跳哪去了？” —— 得一个一个打开 Axure 文件翻
❓ “上个版本的下单流程是啥样？” —— 找了一圈，发现本地没存
❓ “产品又改了？没人通知啊！” —— 只能私聊产品经理问
❓ “客服想看看页面逻辑” —— 可人家打不开 .rp 文件啊

这些问题说白了就一点：Axure 原型“藏得太深”，想查个东西太费劲。

我们试过各种办法，最后发现：用企业微信自带的“智能机器人”，配合 PDF 文档，就能让同事在聊天里直接问出原型内容。

整个过程不用写代码、不花钱、不运维，今天分享下我们是怎么做的。

第一步：把 Axure 原型变成“能被搜”的文档

.rp 是 Axure 自己的格式，电脑没装 Axure 就打不开，更别说让机器人“读懂”了。

我们试了三种办法：

方法	行不行	为啥
转成 PDF	✅ 行	保留目录、交互说明，手机也能看，还能搜文字
转成图片	❌ 不行	看得见但搜不到，改一点就得重传一堆图
转成 Markdown + 图	❌ 不现实	手动维护太累，交互逻辑也丢

✅ 最后我们选了：Axure 导出 PDF

操作特别简单：

打开 Axure
点菜单栏 File → Print
选择 “Save as PDF”
保存就行

第二步：让机器人“学会”这些文档

目标是：谁在某处问“下单流程是啥？”，机器人能直接回。

我们看了两种方案：

方案一：自己搭 RAG（比如 Dify、RAGFlow）

✅ 能自建，数据自己管
✅ 支持上传 PDF、Word、Excel
✅ 可以更好与自身其他系统做对接
❌ 得部署、调参数、维护服务器
❌ 和企业微信不打通，用起来要跳来跳去

方案二：企业微信自带的“智能机器人”

✅ 直接在企业微信里用，谁都会
✅ 支持上传 PDF、Word、Excel
✅ 上传后自动“读”内容，能回答问题
✅ 权限可以控制：谁可以问，谁可以改文档
✅ 手机上也能用，体验很顺
✅ 完全免费，不用操心运维

✅ 最后我们选了企业微信机器人，与其自己辛苦去调参调优，不如让腾讯的开发人员帮你完成这一步。落地快、用着顺、不用费心思调参数和部署。

✅ 怎么搭？手把手教你（手机端操作）

我们主要用手机操作，步骤很简单：

1. 创建机器人

更新企业微信到最新版（V5.0+）
点底部「通讯录」
找到「智能机器人」
点「创建」→「创建智能机器人」
填信息：
- 头像：随便选，我们搞了个绿色的（生活过得去，身上总要一点绿 😂）
- 名字：产品助手
- 简介：APP 的设计问题都可以问我！
- 模型：选 DeepSeek-V3 快速问答
- 知识：先上传几份产品原型 PDF
- 角色设定：留空（不需要）
- 权限：
  - 谁能问？→ 产研团队
  - 谁能改文档？→ 产品经理、研发负责人

✅ 创建完就能用，不需要写一行代码。

🖼️ 实际效果（附截图）

同事直接 @机器人问问题，秒回答案

更多时候是私聊机器人得到答案

支持多种文档来源，不仅能传本地文件，还能直接引用共享的 Doc 文档和 Excel 文档

💡 我们踩过的坑和经验

PDF 是最省事的格式
不用装 Axure，也不用学新工具，谁都能打开，机器人也能“读懂”。
文件名要规范
别叫“最新版.pdf”、“改好了.pdf”，我们统一用：版本_功能_日期_作者.pdf
记得及时更新
每次原型改了，必须重新导出 PDF 并上传，不然机器人“学”的是旧的。
和上线流程绑在一起
我们把“更新知识库”加进了上线 Checklist，确保文档不掉队。

🌟 最后总结

我们没花一分钱，也没搭服务器，就靠企业微信自带的功能，搞定了一个真正能用的知识库。

核心就两点：

Axure 原型导出为 PDF → 让文档“可读、可搜、可分享”
用企业微信智能机器人 → 让同事“在聊天里直接问”

🔗 小提示

企业微信这个功能 9 月份刚推不久，很多人还不知道
相信钉钉、飞书很快也会有类似功能，或已有类似功能
功能完全免费，就算后续收费咱小公司也是用得起的
单个 PDF 最大支持 100M，文档上传后需要几分钟的解析才能使用
从截图可以看出，回答效果是非常好，还能带图！

【新工具上线】yapi_check——让 API 验证不再头疼！

ThxFly — Wed, 13 Mar 2024 15:49:29 +0800

YAPI 是一款比较好用的接口文档管理工具。可见 V 站讨论 https://www.v2ex.com/t/697920

Gem: https://github.com/shootingfly/yapi_check

大家好！

在日复一日的开发工作中，我们常常面临着 API 文档与代码不一致的挑战。无论是确保 API 请求的格式正确，还是验证返回数据的准确性，这一切的工作都显得繁琐且耗时。但现在，有了新工具 yapi_check，这一切都将变得简单和高效！

YapiCheck 说明

yapi_check 是什么？

yapi_check 是一款专为 Rails 开发者设计的 Gem 包，旨在提供一个简洁、易用的 YAPI 验证解决方案。它能帮助你轻松校验 YAPI 请求与响应，确保数据的准确性，从而大幅提高开发效率。

yapi_check 能做什么？

自动验证 YAPI 请求和响应：通过简单的配置，yapi_check 能够自动验证 YAPI 的请求和响应格式，确保它们符合预期。
详细的错误报告：当 API 验证失败时，yapi_check 能够提供详细的错误报告，帮助你快速定位问题所在。
简化测试流程：通过自动化的验证流程，yapi_check 可以帮助你减少手动测试的工作量，让测试更加高效。

如何开始使用？

开始使用 yapi_check 非常简单，只需要几个步骤：

在你的 Gemfile 中添加gem 'yapi_check'。
运行bundle install安装。
根据 yapi_check 的文档设置你的 API 验证规则。
开始享受轻松、高效的 API 验证体验！

技术原理概述

在现代 Web 开发中，API 的准确性和一致性对于应用的稳定性和用户体验至关重要。我们的 Gem，yapi_check，利用了 YAPI 项目开放的 OpenAPI，这使得获取接口文档的元数据（如参数类型等）成为可能。得益于 Ruby 的声明式语法特性、Rails 的惯例式编程，以及 method_source 的支持，我们可以轻松读取和规范化 Rails 项目的源码。通过设定精准的正则匹配规则，yapi_check 能够有效地比对和确保项目的 API 接口与其文档的一致性。

工作流程

配置获取： 首先，从 YAPI 项目配置中获取项目的 token。
接口列表调用： 使用 token 调用接口列表 API，(可选) 筛选指定迭代版本下的接口，并通过路径获取接口 ID。
获取接口详情： 通过接口 ID，获取并提取接口的详细信息，包括路径、请求参数类型和响应参数类型。
请求参数校验： 根据接口路径，提取 controller 对应 action 中的请求参数字段、参数类型、是否必填，并进行参数正确性比对。（注：非 JSON 参数的类型比对不在此范围内）
响应参数校验： 提取 action 对应 jbuilder 的响应参数和类型，进行响应参数的正确性比对。
报告生成： 生成并输出详细的排查报告，指出可能的不一致之处。
自动化执行： 全过程可通过 rake 任务自动化执行，提高效率和准确性。

使用注意

为了确保 yapi_check 的兼容性，请注意以下最佳实践原则：

参数校验： 我们推荐使用 lucky_param 进行参数校验，以确保参数的准确性和安全性。
响应格式： 应通过 jbuilder 来管理响应输出，确保响应的 JSON 数据被正确地封装在"data"对象中，例如{"data": {}}。
文档管理： 我们采用 YAPI 进行接口文档管理。对于需要非接口类文档，请在接口名称的开头明确标注"[接口说明]"。
自定义修改： 如果您的项目实践与上述不完全一致，您可以 fork 此项目并进行必要的修改，之后欢迎提交 MR 以共享您的改进。

请注意，目前我们不支持布尔型参数的校验，布尔型应都用整型参数替代，以支持可能的扩展。

YAPI 接口文档编写规范

ThxFly — Fri, 20 Oct 2023 11:56:36 +0800

我有一个朋友，这是他公司实施的 YAPI 接口文档编写规范，屏蔽了一些涉及技术隐私的规范

接口文档编写规范

枚举值
1. 枚举值参数统一在备注中使用$$后缀注明
2. 于项目中的公共分类中创建/enum 目录，录入枚举值
参数
1. 参数英文名称需与中文注释保持一致
2. 参数需注明参数类型
3. 参数需注明是否必填
4. 参数需提供 mock 值
5. 时间型参数用秒级时间戳形式的整型表示
6. ID 型参数用字符串表示
7. 日期型参数用"YYYY-mm-dd"形式的字符串表示
8. 不下发 null, 用对应类型的空值替代
9. 对象的空值是空对象
10. 数组的空值是空数组
11. 数值型的空值是 0
12. 字符串型的空值是空串
13. 公共参数不应在接口中出现
14. 新项目中，GET 请求使用查询参数，POST 请求使用 JSON 参数
布尔值
1. 布尔类型统一以整型进行上传和下发
2. 0 表示假，1 表示真
3. 布尔型参数统一使用_flag 后缀进行命名，如 valid_flag
4. 命名方式需采用肯定形式，禁止采用双重否定
备注
1. 对接口的每次更改，需于备注中进行注明新增/修改的参数
2. 接口的使用若复杂难懂，需于备注中进行注明
接口名称
1. 采用动宾结构
2. 例外情况：登录、注册等固定搭配
3. 已废弃的接口于名称后尾标注“(已废弃)”,并于接口备注说明废弃版本号
接口请求方式
1. 只存在 GET 和 POST
2. 语义上更偏向获取信息的用 GET
3. 对安全性要求高，涉及到数据变更，需使用请求体传输数据的用 POST
接口路径
1. 函数式命名风格，动宾搭配
2. 获取列表以 list_开头，并采用单数，如 list_user
3. 获取单个数据以 show_开头
4. 创建数据以 create_开头
5. 更新数据以 update_开头
6. 删除数据以 delete_开头
7. 资源型命名空间采用复数命名，整体路径如"/api/v1/users/list_user"
接口状态
1. 当接口与测试服一致时，为已完成
2. 当处于实现中或代码修改中，为未完成
标签
1. 每次新增或修改接口，需打上版本号标签，如"2.0.3", 不带 V
2. 对于以 H5 为主的项目，需打上"原生"标签，注明为原生调用的接口
3. 对于以原生为主的项目，需打上"H5"标签，注明为 H5 调用的接口
4. 对于免登录的接口，需打上"免登录"标签
分类名
1. 分类名为中文单词 + (英文复数), 如"评论 (comments)"
环境配置
1. 环境配置需配置开发、测试、正式三个环境
2. 请求配置需配置预处理代码，便于后台人员在线运行接口
测试集合
1. 每次迭代，涉及的接口需创建测试集合放置
2. 上线测试服，测试集合应能看到对应的调用结果
公共分类
1. 需统一公共参数 /common_params
2. 需统一说明枚举值 /enum
3. 需统一说明接口响应码 /code
4. 其他说明文档也放置于公共分类，如云存储空间说明等
请求头
1. 按需设置请求头
接口设计
1. 设计时需思考调用是否符合人类直觉
2. 设计时需思考参数设计是否能应对需求变更
3. 设计时需思考前端调用接口是否方便
4. 设计时需思考对于扩展是否方便
5. 设计时对接口涉及的改动信息需及时在讨论群组中说明并记录在文档中

Crystal 1.0.0 Released!

ThxFly — Tue, 23 Mar 2021 20:02:45 +0800

https://crystal-lang.org/2021/03/22/crystal-1.0-what-to-expect.html

[预热] Crystal 语言将于 2021 年 3 月发布 1.0.0 版本

ThxFly — Fri, 19 Mar 2021 11:11:49 +0800

期待

PR: https://github.com/crystal-lang/crystal/pull/10500

变更日志：https://github.com/bcardiff/crystal/blob/changelog/1.0.0/CHANGELOG.md

Rails 5.2 不支持 Ruby 3.0

ThxFly — Sun, 27 Dec 2020 22:15:20 +0800

https://github.com/rails/rails/issues/40938

分享一个极简 API 框架——Runcobo

ThxFly — Thu, 24 Sep 2020 00:10:16 +0800

开发背景

Crystal 目前最火的有三个框架

Kemal: Sinatra on Crystal
Amber: Rails on Crystal
Lucky：Crystal 活跃程度最高的一门框架，开发思想为“更少的 bug”

我试用了以上三种，分享些个人的感受：

Kemal 用来做些小项目可以，但商用的话太难，毕竟 Sinatra 的底子给了它一个黑暗的未来；
Amber 用起来行云流水，模仿 Rails 的确很像，应该能吸引一票的 Rails 程序员。但除了 Laravel，其他语言模仿 Rails 的都哑火了，也许是因为 Rails 太过优秀，导致模仿者难以超越前作；
Lucky 更多是面向 Web 开发，这个框架提出的概念有些多。作为前后端分离的践行者，个人更想要一款面向 API 开发的微框架，去掉那些涉及网页开发的概念。

对以上框架不太满意，而这时公司又有 KPI 指标，于是乎我散失了几个周末不打机的美好时光，开发了以公司名字"云康宝"命名的Runcobo 框架.

如果你听过买过或用过云康宝体脂秤与共享秤，那你已自动成为本框架的终身 VIP 用户

第一段代码

require "runcobo"

class HelloWorld < BaseAction
  get "/hello_world"

  call do
    render_plain "Hello World"
  end
end

Runcobo.start

先引入库，然后定义一个 Action，在 Action 中声明接口路径，声明需要渲染”Hello World“，最后启动服务器。

乍一看没啥亮眼的，比不上 Sinatra 的三行情书短小精悍。

但故事才刚刚开始......

控制器

为了避免单个控制器代码过多，采用一个动作一个类的方式（赤裸裸抄袭前文提到的 Lucky 框架）
本着微框架的初心，路由不应该单独定义在一个文件里，故路由作为声明语句，写在对应的动作中
本着约定大于配置的准则，与最少惊讶原则，这里只约定了视图所在的目录"src/views/", 布局所在的目录"src/views/layouts/"
参数先声明，后使用，使用简单且类型安全
支持过滤器
支持多种响应格式，纯文本、HTML 与 JSON
渲染 json 视图采用 jbuilder，Rails 自带的 JSON 引擎，Runcobo 也将它带来了。

稍复杂的代码

class Books::Index < BaseAction
  get "/books"
  query NamedTuple(author: String)
  call do
    books = Book.where(author: params[:author])
    render_jbuilder "books/index"
  end
end

json.array! "books", books do |json, book|
  json.book_id      book.id
  json.author       book.author
  json.name         book.name
  json.published_at book.published_at
end

参数设计

作为一门编译语言搭建的 API 框架，理应参数类型安全。Runcobo 采用参数声明的方式来进行参数解析，从而保证类型安全。与 Kemal、Amber、Lucky 相比，自认为 Runcobo 的参数设计还是比较漂亮的。

URL 类型安全

url NamedTuple(a: String, b: Int32?, c: Bool)

查询参数类型安全

query NamedTuple(a: String, b: Int32?, c: Bool)

表单参数类型安全

form NamedTuple(a: String, b: Int32?, c: Bool)

JSON 参数类型安全

json NamedTuple(a: String, b: Int32?, c: Bool, d: NamedTuple(a: String, b: Int32), e: Array(Int32))

调用方式

params[:a] + params[:b].to_s + params[:d][:a]

如你所见，参数支持嵌套对象、嵌套数组、支持可空，使用上也与 Rails 的参数大致相同，最大的不同便是编译期便确定了参数的类型。Runcobo 采用了宏魔法，使得参数在控制器的展现形式为命名元祖的形式，声明采用命名元组，使用的也是命名元组。（注：命名元组是一种固定大小，不可变的，已知键名及其类型、已知值类型的键值对）

我们公司的使用情况

因为需要保证源码安全，需静态编译，目前我司已在分发给第三方定制客户的服务器 SDK（镜像包）使用了该框架。

总结

如果你喜欢 Crystal 的岁月静好，编译执行与类型安全，那你一定会喜欢 Runcobo；
如果你想像书写接口文档那样书写 API 代码，那你一定会喜欢 Runcobo；
如果你是处女座，享受设计的一致性，那你一定会喜欢 Runcobo；

项目已经发布 1.0.0 版本，如果有想要优化的地方，等你成为贡献者与参与者！项目地址 https://github.com/runcobo/runcobo/ 欢迎 star

更多文档请查看 https://runcobo.github.io/docs/ ，需科学上网

夜已深，未完待续........

ActiveAdmin 定制化实战

ThxFly — Sun, 12 Jul 2020 16:58:22 +0800

ActiveAdmin 是一款基于 Rails 的声明式后台管理框架，能够让大家写后台管理系统时会心一笑，下面是我司在生产中一些定制。

一、换用多个主题

ActiveAdmin 默认主题是灰色的，巨丑。为此，使用他人开源的三个主题包，让客服姐姐和程序员哥哥按照个人喜好选用不同主题。管理员表需加个主题字段

# Gemfile
gem 'active_admin_theme'  # 上下布局主题，比较实用，根据README说明安装，下同
gem 'active_material', '1.4.2' # 上下布局主题，支持移动端，Material Design风格；由于列表页的动作会隐藏，使得这个主题在我司用的人最少
gem 'arctic_admin', '3.0.0'  # 左右布局主题，简约风，支持移动端

// app/assets/stylesheets/active_admin_theme.scss    active_admin_theme这个主题不定制还是会有点丑
$skinMainSecondColor: #606ef0!default;
@import "active_admin/mixins";
@import "active_admin/base";

.site_title {
  color: white!important;
}

select {
  height: 29px;
  margin: 0;
  background-color: white;
  border: 1px solid #e4eaec;
}

a  {
  border-radius: initial!important;
}

table.index_table tr.even td {
  background-color: white;
}

# config/initializers/active_admin.rb
  config.register_stylesheet 'active_admin_theme.css'
  config.register_stylesheet 'active_material_theme.css'
  config.register_stylesheet 'arctic_admin_theme.css'

  config.register_javascript 'active_admin_theme.js'
  config.register_javascript 'active_material_theme.js'
  config.register_javascript 'arctic_admin_theme.js'

class ActiveAdmin::Views::Pages::Base < Arbre::HTML::Document
  def build_active_admin_head
    within head do
      html_title [title, helpers.active_admin_namespace.site_title(self)].compact.join(' | ')

      active_admin_namespace.meta_tags.each do |name, content|
        text_node(tag(:meta, name: name, content: content))
      end

      case current_admin_user.theme
      when 'active_material'
        text_node stylesheet_link_tag('active_material_theme.css')
        text_node javascript_include_tag('active_material_theme.js')
      when 'arctic_admin'
        text_node stylesheet_link_tag('arctic_admin_theme.css')
        text_node javascript_include_tag('arctic_admin_theme.js')
      else
        text_node stylesheet_link_tag('active_admin_theme.css')
        text_node javascript_include_tag('active_admin_theme.js')
      end

      if active_admin_namespace.favicon
        text_node(favicon_link_tag(active_admin_namespace.favicon))
      end

      text_node csrf_meta_tag
    end
  end
end

# app/controllers/admin/home_controller.rb, config/routes.rb
get '/admin/check_theme', to: 'admin/home#check_theme', as: :check_theme

# 切换主题
def check_theme
  theme = case current_admin_user.theme
          when 'active_admin_theme' then 'arctic_admin'
          when 'arctic_admin'       then 'active_material'
          when 'active_material'    then 'active_admin_theme'
          else
            'active_admin_theme'
          end
  current_admin_user.update_columns(theme: theme)
  redirect_back fallback_location: root_path
end

二、更改默认匹配顺序

ActiveAdmin 字符串类型的筛选框默认是模糊匹配，即用 like‘%?%’，这不符合索引优化原则，故改为完全匹配

# config/initializers/active_admin.rb 末尾添加
ActiveAdmin::Inputs::Filters::StringInput.filters.clear
ActiveAdmin::Inputs::Filters::StringInput.filter(:equals, :contains, :starts_with, :ends_with)

三、关闭自动加载关联关系

ActiveAdmin 进入列表页时外键对应的 select 条件框会加载所有关联的 ID，数据表如果有上百万行就会卡死，改为默认关闭

# config/initializers/active_admin.rb
config.include_default_association_filters = false

四、关闭默认列排序

默认情况下，每一列都会生成排序按钮，如果某列没有索引，排序会很慢，改为默认关闭，要用时手动开启

# config/initializers/active_admin.rb
class ActiveAdmin::Views::Pages::TableFor
  class Column
    def sortable?
      return false
    end
  end
end

五、过滤搜索条件的空格

搜索条件如果输多了空格，客服姐姐就会来找你麻烦，默认帮她们去掉

class ApplicationController < ActionController::Base
  before_action :strip_params, only: :index

  def strip_params
    return if params[:q].blank?

    params[:q].each do |k, v|
      params[:q][k] = v.strip
    end
  end
end

六、关闭强参数验证

内部系统，别人要有管理员账号和密码才能黑进来，做不做强参数无所谓，关闭默认的强参数机制，省一些容易出错代码

class ApplicationController < ActionController::Base
  before_action do
    params.permit!
  end
end

七、新增额外列方法

提取对于通用的 column 操作，避免代码重复（具体定义根据自己需求和代码来，以下是示例）

# config/initializers/active_admin.rb
class ActiveAdmin::Views::Pages::TableFor
  # 昵称列，通过user_id在缓存中搜索昵称, 避免关联用户表
  def user_column(attribute)
    column('用户') do |model|
      user_id = model.send(attribute)
      link_to User.nick_name(user_id), admin_user_path(user_id)
    end
  end

  # 手机列，通过user_id在缓存中搜索手机, 避免关联用户表
  def phone_column(attribute)
    column('手机号') do |model|
      user_id = model.send(attribute)
      link_to User.phone(user_id), admin_user_path(user_id)
    end
  end

  # 数据库存储的数字，布尔列
  def bool_column(attribute)
    column(attribute) { |model| model.send(attribute).to_i == 1 ? status_tag('yes') : status_tag('no') }
  end

  # 图片列
  def image_column(attribute, options = {})
    column(attribute) do |model|
      url = model.send(attribute)
      image_tag(url, options) if url.present?
    end
  end

  # 枚举值
  def enum_column(attribute, alias_attribute = nil)
    column(attribute) do |model|
      enums = BaseValue.send(alias_attribute || attribute)
      enums[model.send(attribute)]
    end
  end

  # 时间戳转时间显示
  def time_column(attribute)
    column(attribute) do |model|
      Time.at(model.send(attribute).to_i)
    end
  end
end

八、新增额外行方法

提取通用的 row 操作，避免代码重复

# config/initializers/active_admin.rb
class ActiveAdmin::Views::Pages::AttributesTable
  def user_row(attribute)
    row('用户') do |model|
      user_id = model.send(attribute)
      link_to User.nick_name(user_id), admin_user_path(user_id)
    end
  end

  def phone_row(attribute)
    row('手机号') do |model|
      user_id = model.send(attribute)
      link_to User.phone(user_id), admin_user_path(user_id)
    end
  end

  def bool_row(attribute)
    row(attribute) { |model| model.send(attribute) == 1 ? status_tag('yes') : status_tag('no') }
  end

  # 调用示例       image_row :avatar_qnniu, size: '50', style: 'border-radius: 50%'
  def image_row(attribute, options = {})
    row(attribute) do |model|
      url = model.send(attribute)
      image_tag(url, options) if url.present?
    end
  end

  # 枚举值
  def enum_row(attribute, alias_attribute = nil)
    row(attribute) do |model|
      enums = BaseValue.send(alias_attribute || attribute)
      enums[model.send(attribute)]
    end
  end

  def time_row(attribute)
    row(attribute) do |model|
      Time.at(model.send(attribute).to_i)
    end
  end
end

九、新增通用视图帮助类

不同资源的列表页，当用 user_id 搜索时，都需要显示用户相关的一些按钮，可以提取成一个 helper 类，避免重复定义

# app/controllers/concerns/show_user_helper.rb
module ShowUserHelper
  def self.included(dsl)
    dsl.action_item(:show_user, only: [:index]) do
      user_id = params.dig(:q, :user_id_equals) || params[:user_id]
      resource = User.find_by(user_id: user_id) if user_id.present?
      if resource.present?
       # ......省略好些个按钮
        if authorized?(:view_operates, resource)
          a '日志', href: admin_operates_path(q: { user_id_equals: resource.user_id })
        end
        if authorized?(:generate_temp_password, resource)
          a '生成临时密码', href: generate_temp_password_admin_user_path(resource), 'data-method': :post
        end
      end
    end
  end
end

ActiveAdmin.register_page 'Operates' do
  menu label: '日志管理', parent: '系统管理', priority: 54
  include ShowUserHelper   # 包含helper， 这样上面那些按钮都有了
end

十、自定义页脚

# config/initializers/active_admin.rb
  config.footer = ->(_footer) { MyFooter.build(request) }

# config/initializers/my_footer.rb
class MyFooter < ActiveAdmin::Component
  def self.build(request)
    new.build(request)
  end

  def build(request)
    div do
      a('Change Language', href: '/admin/check_locale')
      span '|'
      a('Change Theme', href: '/admin/check_theme')
    end
  end
end

十一、定制详情页的标题

# 对应model代码里定义实例方法
def display_name
  phone || user_id
end

上面这些实战，主要是通过打开类，修改 ActiveAdmin 源代码的方式操作的。

100 行 Crystal 代码实现 Jbuilder

ThxFly — Sun, 05 Jul 2020 23:56:03 +0800

一、原理

一个 jbuilder 文件，实际对应于一个特殊的哈希对象——Jbuilder 对象，在哈希对象上调用 to_json，便会生成 json 字符串。
哈希生成原理：利用 method_missing, 转发不认识的实例方法，方法名作为键，第一参数作为值，支持块处理。
布局原理：利用源码替换技术替换掉布局文件的yield_content
子视图原理：利用语言自带的 read_file 函数，编译期读取文件

简单介绍下 Crystal 的编译期元编程， {{ }} 和 {% %}是编译期宏的语法格式，长得很像 erb 模板。{{ }}里的东西在编译期会被输出，{% %}里的是编译期控制流，用来控制代码编译的。read_file、run、id 是编译期特有的方法，用于代码生成的。

二、示例代码

require "jbuilder"

plain = Jbuilder.new do |json|
  json.null nil
  json.code 200
  json.msg "ok"
  json.merge!({"code" => 201})
  json.array! "array1", [1, 1.0, "1"]
  json.array!("array2", [1, 2, 3, 4]) do |json, item|
    json.code item
  end
  json.data do |json|
    json.code 400
    json.array! "array3", [1, 1.0, "1"]
  end
  json.set!("custom_field", %w[1 2])
end.to_json

puts plain

三、样例输出

{
  "null":null,
  "code":201,
  "msg":"ok",
  "array1":[
    1,
    1.0,
    "1"
  ],
  "array2":[
    {
      "code":1
    },
    {
      "code":2
    },
    {
      "code":3
    },
    {
      "code":4
    }
  ],
  "data":{
    "code":400,
    "array3":[
      1,
      1.0,
      "1"
    ]
  },
  "custom_field":[
    "1",
    "2"
  ]
}

四、源代码

src/jbuilder.cr

require "json"
require "./jbuilder/version"
require "./jbuilder/embed"

class Jbuilder
  alias Integer = Int8 | Int16 | Int32 | Int64 | Int128 | UInt8 | UInt16 | UInt32 | UInt64 | UInt128
  alias BasicType = Bool | Float32 | Float64 | Integer | Nil | String | Time
  alias BasicObject = Array(BasicObject) | BasicType | Hash(String, BasicObject)   # 定义类型

  def initialize(@result = Hash(String, BasicObject).new)
  end

  # 实际初始化方法， 返回一个哈希
  def self.new : Hash
    new.tap do |json|
      yield json
    end.to_h
  end

 # 转发未定义的实例方法
  macro method_missing(call)
    # 如果调用非自带的感叹号方法，如merge!,  set!， 则抛出编译期异常
    {% if call.name.stringify.ends_with?("!") %}
        {% raise "Values only allowed Array | Tuple | Hash | NamedTuple | #{BasicType}"  %} 
    {% end %}

    {% if call.block %} # 如果块存在，则新建一个jbuilder实例赋值给哈希键
      set!({{call.name.stringify}}, Jbuilder.new {{call.block}})
    {% else %} # 如果块不存在，直接赋值给哈希键
      set!({{call.name.stringify}}, {{call.args.first}})
    {% end %}
  end

  def array!(key : String, array) # 简单处理数组，第一参数作为键，第二参数才是值
    value = [] of BasicObject
    array.each do |item|
      value << item
    end
    @result[key] = value
  end

  def array!(key : String, array) # 使用块处理对象数组，第一参数作为键，第二参数才是值
    value = [] of BasicObject
    array.each do |item|
      value << Jbuilder.new do |json|
        yield json, item
      end
    end
    @result[key] = value
  end

  def hash!(key : String, hash)
    value = {} of String => BasicObject
    hash.each do |k, v|
      value[k.to_s] = v
    end
    @result[key] = value
  end

  def merge!(hash : Hash)
    @result.merge!(hash)
  end

  def set!(key : String, value : Array)
    array!(key, value)
  end

  def set!(key : String, value : Tuple)
    array!(key, value.to_a)
  end

  def set!(key : String, value : Hash)
    hash!(key, value)
  end

  def set!(key : String, value : NamedTuple)
    hash!(key, value.to_h)
  end

  def set!(key : String, value : BasicType)
    @result[key] = value
  end

  def to_h : Hash
    @result
  end
end

src/jbuilder/embed.cr

class Jbuilder
  # 支持布局
  macro embed(filename, io_name, layout_file = nil)
    {% if layout_file %}
      # 布局文件的yield_content在编译时会被子文件的源代码覆盖
      {{ io_name.id }} << {{ read_file(layout_file).gsub(/yield_content/, read_file(filename)).id }}.to_json
      {{ io_name.id }}
    {% else %}
      # 不使用布局文件，嵌套一层Jbuilder.new
      {{ io_name.id }} << {{ run("./embedder.cr", filename) }}
      {{ io_name.id }}
    {% end %}
  end
end

src/jbuilder/embedder.cr

puts <<-Crystal
  # 读取文件
  Jbuilder.new do |json|
    #{File.read(ARGV[0])}
  end.to_json
Crystal

五、实际生产书写的代码如下

布局文件 src/views/layouts/application.jbuilder

Jbuilder.new do |json|
  json.code "200"
  json.msg  "ok"
  json.data do |json|
    yield_content
  end
end

主视图 src/views/applies/my_apply.jbuilder

json.array! "applies", applies do |json, apply|
  {{ read_file("src/views/applies/_base_apply.jbuilder").id }}
end
json.local_updated_at local_updated_at.to_i

局部视图 src/views/applies/_base_apply.jbuilder

json.apply_id     apply.apply_id.to_s
json.code         apply.code.to_s
json.name         apply.name.to_s
json.subtitle     apply.subtitle.to_s
json.rand_number rand(100)
json.uri          apply.uri
json.common_flag  apply.common_flag

项目地址： https://github.com/shootingfly/jbuilder

如何看待 Ruby 自带的 http 库? Net::HTTP

ThxFly — Mon, 29 Jun 2020 19:24:36 +0800

乱七八糟的 API, Ruby 语言中最大的毒瘤

gems.ruby-china.com 挂了

ThxFly — Thu, 09 Apr 2020 17:17:51 +0800

@huacnlee @Rei

gems.ruby-china.com 挂了

微服务如何做聚合接口?

ThxFly — Thu, 09 Apr 2020 14:02:06 +0800

最近，APP 那边要求我们提供一个聚合接口来下发各种增量数据，从而避免进入 APP 首页需要调用众多获取数据接口。

综合评估后，认为 APP 的要求合情合理。

目前能考虑的想法，有两个。

第一种

将该接口做在网关层，通过内部 http 请求，请求多个微服务，将数据聚合下发。

第二种

目前我司的管理后台已单独提取出来做成了一个报表微服务，从而能访问多个数据库的数据。考虑在这个微服务里提供这个接口。

大家有什么建议？

讨人厌的后缀表达式

ThxFly — Thu, 26 Mar 2020 22:00:50 +0800

写了几年 Ruby 了，最烦遇上一长串的代码后面给你来个 if 条件

check_form.update(archive_score: sum, higher_content: params[:higher_content]) if status == 'WAIT_COMMENT'

大家是怎么看待后缀表达式的？

.com 域名搜索和分页都有 bug

ThxFly — Fri, 23 Nov 2018 22:26:29 +0800

ruby-china.com 的搜索和分页都是坏的，而 ruby-china.org 都是好的。两份代码吗？

通过测试代码, 自动生成 postman 文件

ThxFly — Wed, 17 Oct 2018 19:45:16 +0800

0 最终成果预览

1 实现思路

自动化接口测试的同时，通过打日志的形式构建 postman 格式的文本文件

2. 编写 rake 任务

lib/postman.rake

namespace :postman do
  task admin: :environment do
    postman('doc/admin_postman.json', :admin_postman, '轻牛+后台管理接口')
  end
end

def postman(doc, method, name)
  header = <<~JSON
    {
      "variables": [],
      "info": {
        "name": "#{name}",
        "_postman_id": "bce94da3-8aa9-c38e-bdb5-fe8835715887",
        "description": "",
        "schema": "https://schema.getpostman.com/json/collection/v2.0.0/collection.json"
      },
      "item": [
  JSON
  File.write(doc, header)
  send(method)
  File.truncate(doc, File.size(doc) - 1)
  File.write(doc, "]\n}", File.size(doc))
end

def admin_postman
  ENV['GENERATE_POSTMAN'] = 'true'
  dir = 'test/controllers/admin/'
  order_controllers = %w[
    sessions_controller_test.rb
    managers_controller_test.rb
  ]
  order_controllers.each do |x|
    `rails test #{dir}#{x}`
  end
end

3.编写测试 helper

require_relative 'base_helper'
require 'timecop'

Timecop.freeze(Time.new(2018, 6, 1, 20, 10, 59)) # 冻结测试时的时间

module AdminTestHelper
  def postman_logger
    @postman_logger = Logger.new("#{Rails.root}/doc/admin_postman.json")
    @postman_logger.formatter = proc do |_severity, _datetime, _progname, msg|
      msg.to_s
    end
    @postman_logger
  end

  # Add more helper methods to be used by all tests here...
  def send_request(method, url, params, generate_doc_flag: true, code: '200', login_flag: true)
    header = { 'authorization' => Register.generate_gw_token(auth_token: 'm2TfHdaADecAEscTT4FzJ48sz') } if login_flag
    send(method, url, params: params, headers: header)
    assert_equal '200', JSON.parse(@response.body)['code']
    generate_postman(method, params) if ENV['GENERATE_POSTMAN'] && generate_doc_flag
  end

  def generate_postman(method, params)
    action_name = I18n.t(@controller.action_name, scope: 'admin.action_name', locale: 'zh-CN')
    postman_logger.info JSON.pretty_generate(
      name: action_name,
      request: {
        url: {
          raw: @request.original_url.sub('http://www.example.com', '{{WEBSITE}}'),
          host: ['{{HOST}}'],
          port: '{{PORT}}',
          path: @request.path.split('/'),
          query: (method != :get ? [] : params.map { |k, v| { key: k, value: v.to_s, equals: true, description: '' } })
        },
        method: method.upcase,
        header: [
          { key: 'AUTHORIZATION', value: '{{token}}' },
          { key: 'Content-Type', value: 'application/x-www-form-urlencoded' }
        ],
        body:
        if method == :get
          {}
        else
          {
            mode: 'urlencoded',
            urlencoded: params.map { |k, v| { key: k, value: v.to_s, type: 'text', enabled: true } }
          }
        end,
        description: ''
      },
      response: []
    )
    postman_logger.info ','
  end
end
class Admin::BaseControllerTest < ActionDispatch::IntegrationTest
  include ::AdminTestHelper
end

4. 编写测试代码

require 'admin_test_helper'
class Admin::SessionsControllerTest < Admin::BaseControllerTest
  test 'admin_login' do
    send_request(:post, admin_login_admin_sessions_url, { username: managers(:one).username, '123456' })
  end
end

5.运行 rake 任务，在 postman 里导入生成的 postman.json

$ rake postman:admin

p.s 最后把文档导入 Insomnia(更简洁的 api 工具，兼容 postman), 不是 postman