micro-analytics-cli API完全手册：掌握数据追踪与查询的核心方法

【免费下载链接】micro-analytics-cliPublic analytics as a Node.js microservice. No sysadmin experience required! 📈项目地址: https://gitcode.com/gh_mirrors/mi/micro-analytics-cli

想要快速搭建一个轻量级、高性能的数据分析服务吗？micro-analytics-cli 作为一款基于 Node.js 的微服务分析工具，为您提供了简单易用的数据追踪与查询API。这个完整的API手册将带您深入掌握如何通过简洁的HTTP接口实现数据统计、实时监控和高级查询功能。📊

快速入门：安装与启动

在开始使用 micro-analytics-cli API 之前，您需要先安装并启动服务：

npm install -g micro-analytics-cli micro-analytics

服务默认会在localhost:3000端口启动，您可以通过--port参数指定其他端口，或使用--host参数绑定特定主机地址。

核心API端点详解

基础数据追踪接口

路径追踪：GET /:pathname

这是最基础的API端点，用于追踪特定路径的访问次数。每次请求都会自动增加该路径的访问计数。

示例请求：

// 追踪页面访问 fetch('http://localhost:3000/homepage') .then(response => response.json()) .then(data => console.log(`当前访问次数：${data.views}`))

响应格式：

{ "views": 42, "time": 1689123456789 }

查询模式控制

不增加计数的查询：GET /:pathname?inc=false

在某些场景下，您可能只需要查询当前访问次数而不增加计数。这时可以使用inc=false参数。

示例：

// 仅查询不计数 fetch('http://localhost:3000/homepage?inc=false') .then(response => response.json()) .then(data => console.log(`当前访问次数：${data.views}`))

带元数据的POST请求

路径追踪（带元数据）：POST /:pathname

通过POST请求，您可以附加额外的元数据信息，这些信息将与访问记录一起存储。

示例请求：

fetch('http://localhost:3000/homepage', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ meta: { userAgent: navigator.userAgent, referrer: document.referrer, screenSize: `${window.innerWidth}x${window.innerHeight}` } }) })

高级查询功能

批量数据获取

获取所有路径数据：GET /?all=true

这个API端点允许您一次性获取所有已追踪路径的完整统计数据。

响应格式：

{ "data": { "/homepage": { "views": [ { "time": 1689123456000 }, { "time": 1689123457000, "meta": { "userAgent": "Chrome" } } ] }, "/about": { "views": [ { "time": 1689123458000 } ] } }, "time": 1689123456789 }

路径前缀查询

按路径前缀筛选：GET /:prefix?all=true

如果您需要获取特定前缀路径的所有数据，可以使用这个功能。例如，GET /products?all=true将返回所有以/products开头的路径数据。

时间范围筛选

按时间范围查询：GET /:pathname?before=timestamp&after=timestamp

您可以通过before和after参数查询特定时间范围内的访问数据：

// 查询今天的数据 const today = Date.now(); const yesterday = today - 24 * 60 * 60 * 1000; fetch(`http://localhost:3000/homepage?after=${yesterday}&before=${today}`) .then(response => response.json()) .then(data => console.log(`今日访问：${data.views}`))

实时监控API

服务器推送事件（SSE）

实时数据流：GET /_realtime

micro-analytics-cli 支持服务器推送事件，让您可以实时监控数据变化。这个功能需要数据库适配器支持。

客户端实现：

const sse = new EventSource('http://localhost:3000/_realtime'); sse.onopen = () => console.log('实时连接已建立'); sse.onerror = (error) => console.error('实时连接错误：', error); sse.addEventListener('micro-analytics-ping', (event) => { const data = JSON.parse(event.data); console.log('新数据到达：', data); });

健康检查接口

服务状态检查：GET /_healthcheck

这个端点用于检查服务是否正常运行，返回服务的健康状态信息。

数据库适配器API

micro-analytics-cli 的核心数据操作通过适配器接口实现，您可以查看packages/micro-analytics-cli/src/db.js文件了解完整的数据库API：

核心方法

1. get(key, options)- 获取指定键的数据
2. getAll(options)- 获取所有数据
3. put(key, value)- 存储数据
4. has(key)- 检查键是否存在
5. keys()- 获取所有键
6. subscribe(callback)- 订阅数据变化
7. clear()- 清空所有数据

适配器支持

系统支持多种数据库适配器：

1. flat-file-db（默认）- 基于文件的轻量级存储
2. memory- 内存存储（重启后数据丢失）
3. redis- Redis数据库适配器
4. mongodb- MongoDB数据库适配器
5. postgres- PostgreSQL数据库适配器

实用工具函数

在packages/micro-analytics-cli/src/utils.js中，您会找到核心的pushView函数，它实现了原子性的视图推送操作，确保在高并发场景下的数据一致性。

错误处理与状态码

常见HTTP状态码

• 200 OK- 请求成功
• 400 Bad Request- 请求参数错误
• 500 Internal Server Error- 服务器内部错误

错误响应格式

{ "error": "错误描述信息" }

最佳实践指南

1. 网站访问统计

<script> // 在网站每个页面底部添加 window.addEventListener('load', () => { fetch('https://your-analytics-server.com' + window.location.pathname, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ meta: { userAgent: navigator.userAgent, referrer: document.referrer, screenSize: `${window.innerWidth}x${window.innerHeight}` } }) }) .then(response => response.json()) .then(data => { console.log(`页面访问次数：${data.views}`); }) .catch(err => console.error('统计发送失败：', err)); }); </script>

2. API应用监控

// 监控API端点使用情况 async function trackApiUsage(endpoint, userId, method) { const response = await fetch(`https://analytics-server.com/api${endpoint}`, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ meta: { userId, method, timestamp: new Date().toISOString() } }) }); return response.json(); }

3. 实时仪表板

// 构建实时监控仪表板 class AnalyticsDashboard { constructor(serverUrl) { this.serverUrl = serverUrl; this.setupRealtimeConnection(); } setupRealtimeConnection() { this.sse = new EventSource(`${this.serverUrl}/_realtime`); this.sse.addEventListener('micro-analytics-ping', this.handleUpdate.bind(this)); } handleUpdate(event) { const data = JSON.parse(event.data); this.updateDashboard(data); } updateDashboard(data) { // 更新UI显示 console.log('实时数据更新：', data); } }

配置选项详解

命令行参数

micro-analytics [options] 选项： -a, --adapter [value] 数据库适配器（默认："flat-file-db"） -h, --help 显示帮助信息 -H, --host [value] 监听主机（默认："0.0.0.0"） -p, --port <n> 监听端口（默认：3000） -v, --version 显示版本号

环境变量配置

# 使用Redis适配器 DB_ADAPTER=redis micro-analytics # 自定义数据库文件 DB_NAME=custom-views.db micro-analytics # 指定主机和端口 HOST=127.0.0.1 PORT=8080 micro-analytics

性能优化建议

1. 批量处理

对于高频访问的路径，考虑在客户端进行批量处理，减少HTTP请求次数。

2. 适配器选择

• 开发环境：使用memory适配器获得最佳性能
• 生产环境：根据数据量选择redis或postgres适配器

3. 缓存策略

对于不常变化的数据，可以在客户端实现缓存机制，减少对服务器的请求。

故障排除

常见问题解决

1. 服务无法启动

   • 检查端口是否被占用
   • 确认Node.js版本符合要求
   • 查看适配器依赖是否安装完整

2. 数据不更新

   • 确认请求路径正确
   • 检查网络连接
   • 验证数据库适配器配置

3. 实时推送不工作

   • 确认数据库适配器支持subscribe功能
   • 检查浏览器是否支持Server-Sent Events
   • 验证CORS配置

扩展与自定义

自定义适配器开发

如果您需要支持其他数据库，可以参考packages/adapter-utils/中的工具函数和测试用例，快速开发自定义适配器。主要需要实现以下接口：

module.exports = { init: async (options) => { /* 初始化 */ }, get: async (key, options) => { /* 获取数据 */ }, put: async (key, value) => { /* 存储数据 */ }, has: async (key) => { /* 检查存在 */ }, keys: async () => { /* 获取所有键 */ }, getAll: async (options) => { /* 获取所有数据 */ }, subscribe: (callback) => { /* 订阅更新 */ }, clear: async () => { /* 清空数据 */ } };

通过这份完整的API手册，您现在已经掌握了 micro-analytics-cli 的所有核心功能和高级用法。无论是简单的网站访问统计，还是复杂的实时数据分析，这个轻量级的分析工具都能为您提供强大的支持。🚀

记住，micro-analytics-cli 的核心设计理念是简单和高效，让数据分析变得轻松愉快。现在就开始使用这些API，为您的应用添加强大的数据追踪能力吧！

【免费下载链接】micro-analytics-cliPublic analytics as a Node.js microservice. No sysadmin experience required! 📈项目地址: https://gitcode.com/gh_mirrors/mi/micro-analytics-cli