Files

T

2026-06-30 14:46:52 +08:00

13 KiB

Raw Blame History

分享码日志API

**本文档引用的文件** - [ShareCodeLog.js](file://backend/src/models/ShareCodeLog.js) - [shareCodeLogs.js](file://backend/src/routes/shareCodeLogs.js) - [response.js](file://backend/src/utils/response.js) - [auth.js](file://backend/src/middleware/auth.js) - [database.js](file://backend/src/config/database.js) - [index.js](file://backend/src/routes/index.js) - [app.js](file://backend/src/app.js) - [shareCodeLog.js](file://frontend/src/api/shareCodeLog.js) - [log.vue](file://frontend/src/views/share-code/log.vue)

简介

分享码日志API是一个基于Express.js和Sequelize的RESTful API服务，专门用于管理和查询分享码使用记录。该系统提供了完整的日志查询、筛选和统计分析功能，支持设备MAC地址、分享码、操作类型、IP地址等多种维度的查询，并具备分页查询和排序能力。

该API采用MySQL作为数据存储，通过索引优化确保大数据量场景下的查询性能。前端界面提供了直观的日志查询和展示功能，支持时间范围查询、用户筛选和设备类型过滤。

项目结构

分享码日志API位于项目的后端目录中，采用典型的三层架构设计：

graph TB
subgraph "前端层"
FE_API[前端API模块<br/>shareCodeLog.js]
FE_VIEW[前端视图组件<br/>log.vue]
end
subgraph "后端层"
ROUTES[路由层<br/>shareCodeLogs.js]
MIDDLEWARE[中间件层<br/>auth.js]
MODELS[模型层<br/>ShareCodeLog.js]
UTILS[工具类<br/>response.js]
end
subgraph "基础设施层"
CONFIG[配置层<br/>database.js]
APP[应用入口<br/>app.js]
ROUTE_INDEX[路由汇总<br/>index.js]
end
FE_API --> FE_VIEW
FE_VIEW --> ROUTES
ROUTES --> MIDDLEWARE
ROUTES --> MODELS
ROUTES --> UTILS
MODELS --> CONFIG
ROUTES --> ROUTE_INDEX
ROUTE_INDEX --> APP
APP --> CONFIG

图表来源

章节来源

核心组件

数据模型定义

分享码日志模型定义了完整的数据结构和约束条件：

字段名	数据类型	约束条件	描述
id	INTEGER	主键, 自增	日志记录唯一标识
mac_addr	STRING(17)	非空	设备MAC地址，格式如AA:BB:CC:DD:EE:FF
share_code	CHAR(5)	非空	分享码，固定5位字符
action	ENUM	非空	操作类型：export=导出, import=导入
ip_addr	STRING(45)	非空, 默认''	用户IP地址，支持IPv4/IPv6
eq_data	JSON	非空	EQ数据快照，JSON格式存储
expire_at	DATE	可空	分享码到期时间（导出时快照）
create_at	DATE	非空, 默认当前时间	操作时间戳

数据库索引策略

为了优化查询性能，系统建立了以下复合索引：

idx_mac_addr: 基于MAC地址的索引
idx_share_code: 基于分享码的索引
idx_create_at: 基于创建时间的索引

章节来源

ShareCodeLog.js:1-60

架构概览

分享码日志API采用MVC架构模式，结合中间件机制实现认证授权和请求处理：

sequenceDiagram
participant Client as 客户端
participant Auth as 认证中间件
participant Route as 路由处理器
participant Model as 数据模型
participant DB as MySQL数据库
Client->>Auth : 发送带Bearer Token的请求
Auth->>Auth : 验证JWT令牌有效性
Auth->>Route : 通过认证，传递用户信息
Route->>Route : 解析查询参数和过滤条件
Route->>Model : 执行数据库查询
Model->>DB : 发送SQL查询请求
DB-->>Model : 返回查询结果
Model-->>Route : 返回ORM对象数组
Route->>Route : 处理数据格式化和分页
Route-->>Client : 返回标准化响应
Note over Client,DB : 支持多维度查询和分页

图表来源

章节来源

详细组件分析

API接口规范

GET /api/share-code/logs - 日志列表查询

请求参数

参数名	类型	必填	默认值	描述
skip	number	否	0	跳过记录数，用于分页
limit	number	否	100	每页记录数，最大1000
mac_addr	string	否	无	设备MAC地址模糊查询
share_code	string	否	无	分享码模糊查询
action	enum	否	无	操作类型：export/import
ip_addr	string	否	无	IP地址模糊查询
start_at	string	否	无	开始时间（ISO格式）
end_at	string	否	无	结束时间（ISO格式）
sort_by	enum	否	id	排序字段：id/create_at
sort_order	enum	否	desc	排序方式：asc/desc

响应格式

classDiagram
class ApiResponse {
+number code
+string msg
+any data
}
class PageData {
+Item[] items
+number total
+number skip
+number limit
}
class Item {
+number id
+string mac_addr
+string share_code
+string action
+string ip_addr
+object eq_data
+string expire_at
+string create_at
}
ApiResponse --> PageData : "包含"
PageData --> Item : "包含多个"

图表来源

response.js:1-25

响应示例

{
  "code": 1,
  "msg": "success",
  "data": {
    "items": [
      {
        "id": 1,
        "mac_addr": "AA:BB:CC:DD:EE:FF",
        "share_code": "ABCD1",
        "action": "export",
        "ip_addr": "192.168.1.100",
        "eq_data": { /* JSON格式的EQ数据 */ },
        "expire_at": "2024-01-01T12:00:00Z",
        "create_at": "2024-01-01T10:00:00Z"
      }
    ],
    "total": 150,
    "skip": 0,
    "limit": 100
  }
}

章节来源

查询过滤逻辑

系统实现了灵活的查询过滤机制，支持多种组合查询条件：

flowchart TD
Start([开始查询]) --> ParseParams["解析查询参数"]
ParseParams --> BuildWhere["构建WHERE条件"]
BuildWhere --> CheckMac{"MAC地址存在?"}
CheckMac --> |是| AddMac["添加MAC模糊查询"]
CheckMac --> |否| CheckCode{"分享码存在?"}
AddMac --> CheckCode
CheckCode --> |是| AddCode["添加分享码模糊查询"]
CheckCode --> |否| CheckAction{"操作类型存在?"}
AddCode --> CheckAction
CheckAction --> |是| AddAction["添加操作类型过滤"]
CheckAction --> |否| CheckIP{"IP地址存在?"}
AddAction --> CheckIP
CheckIP --> |是| AddIP["添加IP模糊查询"]
CheckIP --> |否| CheckTime{"时间范围存在?"}
AddIP --> CheckTime
CheckTime --> |是| AddTime["添加时间范围查询"]
CheckTime --> |否| ExecuteQuery["执行查询"]
AddTime --> ExecuteQuery
ExecuteQuery --> CheckResult{"有结果?"}
CheckResult --> |是| FormatData["格式化返回数据"]
CheckResult --> |否| ReturnEmpty["返回空数据"]
FormatData --> ReturnSuccess["返回成功响应"]
ReturnEmpty --> ReturnNoData["返回无数据响应"]
ReturnSuccess --> End([结束])
ReturnNoData --> End

图表来源

shareCodeLogs.js:15-84

章节来源

shareCodeLogs.js:31-48

前端集成

前端提供了完整的日志查询界面，支持实时数据展示和交互操作：

sequenceDiagram
participant User as 用户
participant View as 视图组件
participant API as API模块
participant Backend as 后端服务
User->>View : 输入查询条件
View->>View : 构建查询参数
View->>API : 调用getShareCodeLogs()
API->>Backend : 发送HTTP请求
Backend->>Backend : 处理查询逻辑
Backend->>Backend : 应用过滤条件
Backend->>Backend : 执行数据库查询
Backend-->>API : 返回查询结果
API-->>View : 返回响应数据
View->>View : 更新表格显示
View->>User : 展示查询结果
Note over User,Backend : 支持分页、排序、筛选

图表来源

章节来源

依赖关系分析

技术栈依赖

分享码日志API采用现代化的Node.js技术栈，各组件之间的依赖关系如下：

graph LR
subgraph "核心框架"
Express[Express.js]
Sequelize[Sequelize ORM]
MySQL[MySQL驱动]
end
subgraph "认证授权"
JWT[JWT Token]
Auth[认证中间件]
end
subgraph "工具库"
CORS[CORS跨域]
Winston[Winston日志]
Dotenv[环境变量]
end
subgraph "前端集成"
ElementPlus[Element Plus UI]
Axios[Axios HTTP]
end
Express --> Sequelize
Sequelize --> MySQL
Express --> Auth
Auth --> JWT
Express --> CORS
Express --> Winston
Express --> Dotenv
ElementPlus --> Axios

图表来源

package.json:11-27

组件耦合度分析

系统采用了低耦合的设计原则：

路由层与模型层分离: 路由处理只负责请求接收和响应格式化
中间件独立性: 认证中间件可复用到其他路由
配置集中管理: 数据库连接和环境配置统一管理
工具类模块化: 响应格式化等工具函数独立封装

章节来源

package.json:1-29

性能考虑

查询优化策略

针对大数据量场景，系统采用了多项性能优化措施：

索引优化: 为常用查询字段建立复合索引
分页限制: 单次查询最大返回1000条记录
查询条件优化: 支持多条件组合查询，避免全表扫描
时间范围查询: 优先使用时间索引进行范围查询

缓存策略

虽然当前版本未实现专用缓存，但系统具备良好的扩展性：

flowchart LR
Request[请求到达] --> CheckCache{检查缓存}
CheckCache --> |命中| ReturnCache[返回缓存数据]
CheckCache --> |未命中| QueryDB[查询数据库]
QueryDB --> FormatData[格式化数据]
FormatData --> StoreCache[存储到缓存]
StoreCache --> ReturnData[返回响应]
ReturnCache --> End[结束]
ReturnData --> End

大数据量处理

对于超大数据量的场景，建议采用以下策略：

时间分区: 按月或按季度对日志表进行分区
归档策略: 将历史数据迁移到归档表
异步处理: 对复杂的统计分析采用异步任务队列
读写分离: 主从复制实现读写分离

故障排除指南

常见错误及解决方案

错误类型	错误码	描述	解决方案
认证失败	401	未登录或缺少凭证	检查Authorization头是否正确设置
权限不足	403	需要超级管理员权限	确认用户具有相应权限
参数错误	400	请求参数格式不正确	验证查询参数的格式和类型
数据库错误	500	数据库操作失败	检查数据库连接和SQL语句

日志监控

系统内置了完善的日志记录机制：

graph TD
subgraph "日志级别"
Info[Info日志]
Error[Error日志]
Warn[Warn日志]
end
subgraph "监控指标"
QueryCount[查询次数统计]
ErrorRate[错误率监控]
ResponseTime[响应时间]
DBConnection[数据库连接状态]
end
Info --> QueryCount
Error --> ErrorRate
Info --> ResponseTime
Info --> DBConnection

章节来源

结论

分享码日志API是一个功能完整、架构清晰的RESTful服务。它提供了：

完整的查询功能: 支持多维度、多条件的灵活查询
高性能设计: 通过索引优化和分页机制保证查询效率
安全可靠: 基于JWT的认证授权机制确保系统安全
易于扩展: 模块化的架构设计便于功能扩展和维护

该API为分享码使用情况的监控和分析提供了强有力的技术支撑，能够满足日常运营和数据分析的各种需求。随着业务的发展，可以在此基础上进一步完善统计分析、报表生成和趋势预测等功能。

13 KiB Raw Blame History

分享码日志API

目录

简介

项目结构

核心组件

数据模型定义

数据库索引策略

架构概览

详细组件分析

API接口规范

GET /api/share-code/logs - 日志列表查询

查询过滤逻辑

前端集成

依赖关系分析

技术栈依赖

组件耦合度分析

性能考虑

查询优化策略

缓存策略

大数据量处理

故障排除指南

常见错误及解决方案

日志监控

结论

13 KiB

Raw Blame History