企业官网建设流程全解析

• 运维观测
• 指标监控
• 告警

Expression（表达式）是 Open-Falcon Falcon-Plus 中面向「机器无关」场景的告警规则，用于对指定 metric 的全部上报数据做统一判定（例如检测某个 endpoint 的 agent 是否全部失联）。本文聚焦其中的查询接口按 ID 获取表达式详情：完整讲解请求方式、鉴权前提、返回的 expression 与 action 两级 JSON 结构及每个字段的业务含义，并结合仓库源码（API 路由、Controller、数据模型与建表 SQL）说明该接口的底层实现与数据来源，最后给出它在创建、列表、更新、删除等表达式全生命周期 API 中的位置，方便你在二次开发或排查问题时直接对照源码。

接口概览

按 ID 查询表达式属于 Expression 模块的核心只读接口，完整信息如下：

该接口对应的路由声明位于 expression_routes.go：路由组/api/v1/expression整体挂载了utils.AuthSessionMidd会话鉴权中间件，其中expr.GET("/:eid", GetExpression)即为本接口的路由绑定，路径参数eid即表达式 ID。

鉴权：Session 前提

接口文档标注Session Required。在 auth_middle.go 中实现的AuthSessionMidd会校验请求携带的会话凭证，未登录或会话失效的请求会被拒绝。调用前请先通过用户登录接口获取会话，再携带会话 Cookie/凭证发起本查询。

完整响应示例与字段解读

以GET /api/v1/expression/5为例，成功时返回Status: 200，响应体如下：

{ "action": { "id": 5, "uic": "taipei", "url": "", "callback": 0, "before_callback_sms": 0, "before_callback_mail": 0, "after_callback_sms": 0, "after_callback_mail": 0 }, "expression": { "id": 5, "expression": "each(metric=agent.alive endpoint=docker-agent)", "func": "all(#3)", "op": "==", "right_value": "0", "max_step": 3, "priority": 2, "note": "this is a test exp", "action_id": 177, "create_user": "root", "pause": 1 } }

该接口一次性返回expression（表达式本体）与action（关联的告警动作）两块数据，二者通过expression.action_id关联。下面逐一说明。

expression 对象字段

expression 部分对应数据库expression表的记录，字段语义如下：

这些字段与 expression.go 中Expression结构体的 GORM 映射一一对应，也与 2_portal-db-schema.sql 中expression建表语句一致。建表 SQL 中可见各字段的默认值（如func默认all(#1)、max_step默认1、priority默认0、pause默认0），可作为字段取值范围的有力参考。

action 对象字段

action 部分来自action表（对应 action.go 中的Action结构体），描述表达式命中后的通知/回调行为：

上述字段在 2_portal-db-schema.sql 的action建表语句中均有对应列，类型为TINYINT(4)且默认0。

源码实现：查询背后发生了什么

该接口的处理器是 expression_controller.go 中的GetExpression函数，其执行链路非常清晰：

1. 从路由参数:eid取出表达式 ID，缺失时返回400及错误信息eid is missing；ID 无法解析为整数时同样返回400。
2. 通过db.Falcon.Where("id = ?", eid).Find(&expression)从falcon_portal数据库的expression表按主键查询表达式记录；查不到时返回400。
3. 以表达式记录的ActionId为条件，通过db.Falcon.Find(&action)查询action表对应记录，作为关联的告警动作。
4. 将expression与action组装成map[string]interface{}返回。

从源码结构可以推断：本接口采用「表达式 + 动作」两表联查后合并输出的方式，而不是返回单个扁平对象，因此调用方拿到响应后可以直接获得完整的告警配置，无需二次调用动作查询接口。

字段约束：创建/更新时的合法值

虽然查询接口本身不校验输入，但表达式的op与right_value在创建（CreateExrpession）和更新（UpdateExrpession）入口都有格式校验，逻辑位于 expression_controller.go：

• op必须匹配正则^(>|=|<|!)(=)?$，即合法的比较符为>、>=、=（==）、<、<=、!（!=）；
• right_value必须匹配正则^\-?\d+(\.\d+)?$，即可以是负数、整数或小数。

这意味着你在读取查询结果并手工构造其他表达式时，应保证上述字段符合该格式，否则创建/更新接口会返回op's formating is not vaild或right_value's formating is not vaild。

表达式在监控链路中的消费：查询结果的用途

按 ID 查询返回的表达式记录，最终会进入实际告警判定链路，理解这一点有助于判断查询结果的正确性。在 Falcon-Plus 中：

• HBS 模块周期性从falcon_portal数据库读取所有表达式，并通过 RPCHbs.GetExpressions提供给 Judge；
• Judge 模块在 strategy.go 的syncExpression中定期同步表达式，按metric/tag=value维度重建ExpressionMap内存索引，随后对上报数据进行匹配与判定。

因此，你通过本接口查询到的expression字段内容（如each(metric=agent.alive endpoint=docker-agent)）、func、op、right_value、max_step、pause等，正是 Judge 判定时所依赖的原始配置；pause=1的记录在链路中会被视为暂停、不参与告警。若线上告警行为与预期不符，可先通过本接口核对这几项配置是否与预期一致。

在表达式 API 家族中的位置

本接口是 Expression 模块五个 API 之一，其余接口及对应处理函数如下，便于横向对照：

其中创建接口（见文档 expression_create.md）要求以action对象（含uic、url、callback及各回调开关）随请求体提交，创建时在同一事务内先写入action表再写入expression表，并把新 action 的 ID 回填到expression.action_id——这正是本查询接口能返回完整action对象的原因。列表接口（见文档 expression_list.md）返回的则是纯expression数组，不包含 action 详情，因此需要完整配置时按 ID 查询是更合适的选择。

另外值得注意的是，更新与删除接口均包含权限控制：非管理员用户只能操作create_user为自己的表达式，否则会收到You don't have permission!错误（见 expression_controller.go 与 L291-L298）。因此，当你通过本接口查看到create_user字段后，也能据此判断当前登录用户是否具备对该表达式进行后续修改/删除的权限。

常见问题与排查建议

• 返回 400 且提示eid is missing：说明 URL 中未携带表达式 ID，请检查请求路径是否为/api/v1/expression/{整数}格式。
• 返回 400 但无明确提示：多因表达式 ID 不存在（数据库中无对应记录），可先用列表接口确认 ID 是否有效。
• action为空：若表达式的action_id指向的记录已被删除，查询将返回 400（源码中find action got error分支）。创建表达式时 action 与 expression 在同一事务写入，正常情况下两者应同时存在。
• pause字段含义：1表示暂停，表达式不会被 Judge 使用，但记录仍可被查询到，这是区分「配置存在」与「实际生效」的关键字段。

小结

GET /api/v1/expression/{expression_id}是 Falcon-Plus 中查看单条表达式完整配置（含关联告警动作）的标准接口。通过本文你可以掌握：接口的鉴权前提、两级 JSON 响应的全部字段含义与取值范围（对照 建表 SQL 与 数据模型）、底层两表联查的实现细节（expression_controller.go），以及该记录在 HBS→Judge 判定链路中的实际作用。在实际运维与二次开发中，推荐与创建、列表、更新、删除接口配合使用，形成表达式的完整管理闭环。

• 运维观测
• 指标监控
• 告警