企业官网建设流程全解析

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

本篇技术指南聚焦 falcon-plus（Open-Falcon 企业级监控系统）中DashboardScreen（监控大屏）全量列表查询接口的完整使用方式，包含请求格式、limit分页参数说明、返回数据结构，以及该接口在 API 模块中的路由注册、鉴权中间件与底层数据库查询实现。读完本文，你将能够独立调用该接口获取系统内所有监控大屏，并理解其与 Screen 树形层级、Graph 图表绑定的关系。

接口概述

DashboardScreen 是 falcon-plus 中用于组织监控图表的"屏幕（Screen）"资源，每个 Screen 可以拥有父级（pid），从而形成树形层级；同一屏幕下可挂载多个 dashboard graph 图表。本文讲解的"获取全部屏幕"接口用于一次性拉取整个系统中所有 Screen 记录，常用于 dashboard 前端初始化、屏幕列表导航或数据迁移场景。

该接口对应的路由在源码中的注册位置为 dashboard_screen_routes.go，由GET("/screens", ScreenGetsAll)定义，并统一挂载在鉴权分组/api/v1/dashboard之下：

authapi := r.Group("/api/v1/dashboard") authapi.Use(utils.AuthSessionMidd) authapi.POST("/screen", ScreenCreate) authapi.GET("/screen/:screen_id", ScreenGet) authapi.GET("/screens/pid/:pid", ScreenGetsByPid) authapi.GET("/screens", ScreenGetsAll) authapi.DELETE("/screen/:screen_id", ScreenDelete) authapi.PUT("/screen/:screen_id", ScreenUpdate)

路由组在 controller/routes.go 中通过dashboard_screen.Routes(r)注册到全局 gin 引擎，随 API 模块一起启动。

请求说明

鉴权（Session Required）

该接口属于受保护资源，调用前必须通过会话校验。falcon-plus 的 API 采用Apitoken请求头传递会话信息，格式为 JSON 字符串：

{ "Apitoken": "{\"name\":\"root\",\"sig\":\"427d6803b78311e68afd0242ac130006\"}" }

其中name为用户名，sig为会话签名。请求处理时，中间件AuthSessionMidd（见 auth_middle.go）会调用h.SessionChecking完成校验：先读取Apitoken头解析出name与sig，若配置了default_token且sig与之相等则直接放行（用于服务端内部访问）；否则在user表与session表中比对用户名和签名，两者均存在才返回auth = true（见 session.go）。

需要注意的是，配置项skip_auth为true时会跳过鉴权检查（生产环境不建议开启）。若鉴权失败，接口返回401 Unauthorized。完整的会话建立方式可参考 2017-01-01-authentication.md 文档。

参数说明

参数以 URL query 形式传递（GET请求），Content-type 声明为application/x-www-form-urlencoded。参考请求：

GET /api/v1/dashboard/screens?limit=10

从源码看，limit的读取逻辑为c.DefaultQuery("limit", "500")（见 dashboard_screen_controller.go），即未显式传参时默认返回最多 500 条记录；传入非法数值时可能被 ORM 层忽略或返回空列表，建议显式传入正整数。

响应说明

成功响应（Status: 200）

接口成功时返回 HTTP200，响应体为 JSON 数组，数组中的每个元素对应一条dashboard_screen记录，字段包括id（屏幕 ID）、name（屏幕名称）、pid（父屏幕 ID，0 表示顶级屏幕）。参考响应示例：

[ { "id": 952, "name": "a1", "pid": 0 }, { "id": 953, "name": "aa1", "pid": 952 }, { "id": 968, "name": "laiwei-screen2", "pid": 1 }, { "id": 972, "name": "laiwei-sceen1", "pid": 0 }, { "id": 991, "name": "xnew", "pid": 972 }, { "id": 993, "name": "clone3", "pid": 972 }, { "id": 995, "name": "op", "pid": 0 } ]

从示例数据可以直观理解 Screen 的树形结构：id=952与id=972均为顶级屏幕（pid=0），而id=953、id=991、id=993分别挂在952、972之下作为子屏幕。响应中未包含数据库中的time字段，这是因为 ORM 模型只序列化了id、pid、name三个字段（见 dashboard_screen.go）。

响应封装逻辑位于 simple_reponse.go：当状态码为 200 且消息体为非字符串时，直接以原结构体序列化输出；出错时则返回{"error": "..."}形式的错误对象。

错误响应

关于鉴权失败、参数非法等错误场景的状态码约定，请参见 response status codes 文档。

底层实现与数据模型

处理器实现

ScreenGetsAll是"获取全部屏幕"的核心处理器，位于 dashboard_screen_controller.go：

func ScreenGetsAll(c *gin.Context) { limit := c.DefaultQuery("limit", "500") screens := []m.DashboardScreen{} dt := db.Dashboard.Table("dashboard_screen").Limit(limit).Find(&screens) if dt.Error != nil { h.JSONR(c, badstatus, dt.Error) return } h.JSONR(c, screens) }

其执行链路为：解析limitquery 参数（默认 500）→ 通过 GORM 在db.Dashboard连接池中查询dashboard_screen全表并应用Limit→ 将结果绑定到[]DashboardScreen切片 → 查询出错时返回400 Bad Request，成功则直接输出 JSON 数组。

这里使用db.Dashboard而不是主库，说明 Screen 数据存放于独立的 dashboard 数据库连接池（对应config/下 API 配置中的 dashboard 数据源），与 falcon_portal、uic 等业务库分离。

数据表结构

dashboard_screen表定义见 3_dashboard-db-schema.sql：

CREATE TABLE `dashboard_screen` ( `id` int(11) unsigned NOT NULL AUTO_INCREMENT, `pid` int(11) unsigned NOT NULL DEFAULT '0', `name` char(128) NOT NULL, `time` timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP, PRIMARY KEY (`id`), KEY `idx_pid` (`pid`), UNIQUE KEY `idx_pid_n` (`pid`,`name`) ) ENGINE=InnoDB DEFAULT CHARSET=utf8;

几个值得注意的设计点：

• pid默认 0 表示顶级屏幕，配合idx_pid索引，使"按父屏幕查询子屏幕"（即GET /screens/pid/:pid接口，参见 dashboard_screen_gets_by_pid 文档）高效执行；
• (pid, name)上的唯一键保证同一父屏幕下不允许重名，创建接口 dashboard_screen_create 文档 中使用insert ignore写入，重复创建同名屏幕会被静默忽略；
• ORM 模型 dashboard_screen.go 中TableName()方法返回dashboard_screen，与上述表结构严格对应。

与相邻接口的关联

本接口是 DashboardScreen 六件套 API（创建 / 按 ID 查询 / 按 PID 查询 / 全量查询 / 删除 / 更新）中的"全量查询"成员，全部由 dashboard_screen_routes.go 统一注册。在实际使用中，前端通常先调用本接口获取全部屏幕列表，再配合GET /api/v1/dashboard/screen/:screen_id或按pid过滤来定位具体屏幕，最后通过 dashboard graph 相关接口（见 dashboard_graph_routes.go）加载屏幕下的图表数据。

使用建议

• 控制返回规模：全量接口默认上限 500 条，若系统内屏幕数量较大，建议始终显式携带limit，并结合按pid查询接口进行分页或分片拉取，避免一次性返回过多数据；
• 鉴权前置：调用前需先通过登录接口获取有效会话签名sig，并检查 API 配置中skip_auth与default_token的设置，确保请求头携带正确的Apitoken；
• 利用树形结构：响应中的pid字段可直接用于在前端构建"屏幕 → 子屏幕"的树形导航，与name一起渲染屏幕选择器或分组视图。

如需查看更多 DashboardScreen 相关接口的用法，可继续阅读 DashboardScreen 文档目录 下的创建、按 ID 查询、更新与删除文档，或直接在 API 源码目录 中查看对应处理器实现。

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