ClickHouse 是典型的列式数据库，擅长在海量数据上做聚合分析，而 Vue 3 项目通常负责把分析结果呈现给用户。两者之间如果缺少一层工程化封装，开发者很容易在前端代码里散落各种 SQL 拼接和连接配置，时间一长就变得难以维护。更危险的是，有人会尝试在浏览器里直接请求 ClickHouse 的 HTTP 接口，把账号密码和查询语句全部暴露出来。因此，在动手写代码之前，先要明确一条原则：前端永远不直接连接 ClickHouse，所有查询都通过后端中间层完成。
这个中间层可以是一个独立的 Node.js 服务，也可以是现有后端的一部分。它的职责包括管理 ClickHouse 连接、对查询参数做校验、统一处理错误和超时，并把结果转换成前端容易消费的 JSON 格式。Vue 3 只需要关心如何调用接口、如何缓存数据、如何展示。
一、为什么前端工程化要先解决 ClickHouse 访问边界
ClickHouse 提供了 HTTP 接口，理论上浏览器可以通过 fetch 直接发送查询。但这样做会把数据库地址、用户名和密码写进前端代码，任何人打开浏览器开发者工具都能看到。更严重的是，前端无法有效限制查询范围，恶意用户可以构造任意 SQL 拖垮数据库。即使只是内部系统，这种暴露面也会带来极大的安全风险。
工程化的核心思路是把 ClickHouse 的访问权限收口到后端。前端只调用业务化接口，比如传入时间范围和筛选条件，由中间层拼装 SQL 并执行。这样既能隐藏连接信息，又能在服务端做参数校验、白名单控制和查询超时限制。对 Vue 3 开发者来说，前端代码不再出现任何数据库细节，只面对一组清晰的 API。
另一个被忽视的问题是连接管理。ClickHouse 不像 MySQL 那样需要严格的长连接池，但频繁创建 TCP 连接同样会增加延迟。中间层可以复用客户端实例，并且根据并发情况调整查询队列。如果前端直接连接，每个浏览器标签页都会建立独立连接，这在数据大屏或多标签场景下会迅速耗尽服务端资源。
二、用 Node.js 中间层封装 ClickHouse 查询
Node.js 生态里常用的 ClickHouse 客户端是 @clickhouse/client，它同时支持 HTTP 和 TCP 协议。初始化时只需要把连接参数放到环境变量里，避免硬编码。下面是一个最小可用的服务端示例，演示如何创建客户端并执行一个带参数的聚合查询。
import { createClient } from '@clickhouse/client'
const client = createClient({
url: process.env.CLICKHOUSE_URL,
username: process.env.CLICKHOUSE_USER,
password: process.env.CLICKHOUSE_PASSWORD,
database: process.env.CLICKHOUSE_DB,
})
export async function getEventStats(startTime: string, endTime: string) {
const result = await client.query({
query: `
SELECT
event_type,
count() AS cnt
FROM events
WHERE event_time >= {start:DateTime}
AND event_time < {end:DateTime}
GROUP BY event_type
ORDER BY cnt DESC
`,
query_params: {
start: startTime,
end: endTime,
},
format: 'JSONEachRow',
})
return await result.json()
}
注意查询中的 {start:DateTime} 和 {end:DateTime} 是 ClickHouse 的参数占位符，配合 query_params 使用可以避免 SQL 注入。时间条件写成参数后，传入的字符串会被当作值处理，而不是直接拼进 SQL 文本。这种写法比字符串拼接安全得多，也更容易维护。
在实际项目中，建议不要把 SQL 散落在各个接口里，而是集中到一个查询模块。可以按业务域拆分文件，例如 queries/eventQueries.ts、queries/userQueries.ts，每个函数接收受限的参数并返回结构化数据。这样做的好处是后续修改表结构或优化查询时，只需要改动中间层，不会影响 Vue 3 前端代码。
三、Vue 3 里的数据请求与状态管理封装
前端拿到中间层接口后，不应该在每个组件里重复写 axios 请求和 loading 状态。借助组合式 API，可以把查询逻辑抽成一个可复用的 composable。下面是一个简单的实现，它接收查询标识和参数，返回数据、加载状态、错误对象以及手动触发执行的方法。
import { ref } from 'vue'
import axios from 'axios'
interface EventStat {
event_type: string
cnt: number
}
export function useClickHouseQuery(params: Record<string, unknown>) {
const data = ref([] as EventStat[])
const loading = ref(false)
const error = ref(null as Error | null)
async function execute() {
loading.value = true
error.value = null
try {
const response = await axios.post('/api/clickhouse/event-stats', params)
data.value = response.data
} catch (err) {
error.value = err as Error
} finally {
loading.value = false
}
}
return { data, loading, error, execute }
}
使用时只需要在组件里调用 useClickHouseQuery，在 onMounted 或用户点击查询按钮时执行 execute。模板中根据 loading 和 error 展示不同状态，数据渲染部分可以配合虚拟滚动组件处理大量行。这样数据请求逻辑和业务组件解耦，后续替换中间层接口或增加缓存策略也不会牵一发动全身。
对于复杂查询，前端最好维护一套查询参数类型。比如定义 EventQueryParams 接口，包含 startTime、endTime、eventTypes 等字段。组件在发起请求前先做基础校验，例如时间范围不能超过 31 天，避免一次查询拉取过多数据。这种前置校验能有效保护后端和数据库。
四、针对列式数据库的查询优化和缓存策略
ClickHouse 的列式存储决定了查询优化与关系型数据库有较大差异。最基础的一条是不要使用 SELECT *，因为每次读取都会把所有列从磁盘加载到内存，哪怕前端只需要其中两三个字段。显式列出需要的列可以大幅减少 IO。例如大屏展示只需要 event_type 和 cnt，就只查这两列。
分区裁剪同样重要。如果表按天分区，查询时尽量带上时间范围条件，让 ClickHouse 只读取相关分区。配合 ORDER BY 里的排序键，可以在索引层面快速过滤。比如建表时用 PARTITION BY toYYYYMM(event_time)，查询条件 event_time >= '2024-01-01' AND event_time < '2024-02-01' 就只会扫描一月分区。若前端查询跨度固定为最近 7 天或 30 天，可以在中间层强制限制，防止用户请求全表范围。
缓存方面，分析型查询的结果往往适合短时间缓存。可以在中间层引入 Redis，对相同查询参数的结果缓存 30 秒到几分钟，减少重复请求对 ClickHouse 的压力。但要注意缓存键必须包含全部查询参数和版本号，避免数据更新后返回旧结果。前端也可以配合 Pinia 或简单的 Map 做内存缓存，在单页会话内避免重复请求。
当查询结果达到几十万行时，前端渲染也会成为瓶颈。除了用虚拟滚动，还可以在 SQL 层面做聚合后再返回，或者使用 ClickHouse 的 LIMIT 和分页。不过列式数据库更适合聚合而不是逐页翻看明细，建议把明细查看做成单独接口，并按时间范围进一步过滤，而不是把整个百万行结果塞给浏览器。
Vue 3ClickHouse列式数据库修改时间：2026-09-24 12:04:51