跳到主要内容

字典日志API

引用文件

本文引用的文件

目录​

  1. 简介
  2. 项目结构
  3. 核心组件
  4. 架构总览
  5. 详细组件分析
  6. 依赖关系分析
  7. 性能考虑
  8. 故障排查指南
  9. 结论
  10. 附录

简介​

本文件面向“字典管理”与“日志管理”的API使用与实现，覆盖以下能力：

  • 字典数据接口：字典类型查询、字典项管理；App端按类型查询字典数据；RPC层字典数据校验与解析。
  • 日志接口：登录/访问日志查询、操作日志记录、异常日志记录；支持分页、导出、翻译增强。

文档同时给出数据结构、查询条件与分页机制说明，并提供字典缓存策略、日志审计要求与性能优化建议，帮助开发者与运维人员高效落地与维护。

项目结构​

围绕“字典”与“日志”两大主题，相关模块分布如下：

  • 系统模块（system）：字典类型/字典数据的管理后台接口、App端接口、RPC接口。
  • 基础设施模块（infra）：API访问日志、API错误日志、操作日志的查询与导出接口。
  • 文档（docs）：系统字典管理与基础设施API日志的使用说明。

Mermaid Diagram Code:

graph TB
subgraph "系统模块"
SYS_API["System API<br/>DictDataApi"]
SYS_ADMIN_DICT["管理后台字典接口<br/>DictTypeController / DictDataController"]
SYS_APP_DICT["App字典接口<br/>AppDictDataController"]
end
subgraph "基础设施模块"
INFRA_ACCESS_LOG_API["API访问日志RPC接口<br/>ApiAccessLogApi"]
INFRA_ERROR_LOG_API["API异常日志RPC接口<br/>ApiErrorLogApi"]
INFRA_ACCESS_LOG_CTRL["API访问日志管理接口<br/>ApiAccessLogController"]
INFRA_OPERATE_LOG_CTRL["操作日志管理接口<br/>OperateLogController"]
end
SYS_ADMIN_DICT --> SYS_API
SYS_APP_DICT --> SYS_API
INFRA_ACCESS_LOG_CTRL --> INFRA_ACCESS_LOG_API
INFRA_ACCESS_LOG_CTRL --> INFRA_ERROR_LOG_API

图表来源

章节来源

核心组件​

  • 字典类型管理接口：提供创建、更新、删除、分页查询、详情查询、简单列表、导出等能力。
  • 字典数据管理接口：提供新增、修改、删除、分页查询、详情查询、简单列表、导出等能力。
  • App端字典接口：按字典类型查询启用状态的字典数据列表。
  • RPC字典接口：提供字典数据校验、解析、按类型获取列表、标签列表等能力。
  • 操作日志接口：提供分页查询、导出Excel能力。
  • API访问/异常日志接口：提供分页查询、导出Excel、异步创建能力。

章节来源

架构总览​

系统通过“管理后台接口 + App接口 + RPC接口”三层协同实现字典能力；日志能力由“管理后台日志接口 + RPC日志接口”协同完成。API访问/异常日志由网关或过滤器自动采集并通过RPC异步落库。

Mermaid Diagram Code:

sequenceDiagram
participant Client as "客户端"
participant AdminCtrl as "管理后台字典接口"
participant AppCtrl as "App字典接口"
participant Rpc as "RPC字典接口"
participant AccessLogCtrl as "API访问日志接口"
participant ErrorLogCtrl as "API异常日志接口"
Client->>AdminCtrl : "管理后台字典操作"
AdminCtrl-->>Client : "返回分页/详情/列表"
Client->>AppCtrl : "按类型查询字典数据"
AppCtrl->>Rpc : "RPC查询字典数据"
Rpc-->>AppCtrl : "返回字典数据"
AppCtrl-->>Client : "返回字典列表"
Note over AccessLogCtrl,ErrorLogCtrl : "API访问/异常日志由过滤器自动采集并异步写入"

图表来源

详细组件分析​

字典类型管理接口​

  • 接口路径：/system/dict-type
  • 主要能力：
    • 创建：POST /create
    • 更新：PUT /update
    • 删除：DELETE /delete
    • 分页查询：GET /page
    • 详情查询：GET /get
    • 简单列表：GET /list-all-simple 或 /simple-list
    • 导出：GET /export
  • 权限控制：均需相应权限，如 system:dict:create/update/query/delete 等。
  • 分页机制：使用 PageParam 的分页参数，导出时设置 PAGE_SIZE_NONE 获取全量。
  • 查询条件：分页请求对象包含字典类型筛选字段（具体字段以 VO 类为准）。

Mermaid Diagram Code:

flowchart TD
Start(["请求进入"]) --> Create["POST /create"]
Start --> Update["PUT /update"]
Start --> Delete["DELETE /delete"]
Start --> Page["GET /page"]
Start --> GetDetail["GET /get"]
Start --> SimpleList["GET /list-all-simple"]
Start --> Export["GET /export"]
Create --> End(["返回结果"])
Update --> End
Delete --> End
Page --> End
GetDetail --> End
SimpleList --> End
Export --> End

图表来源

章节来源

字典数据管理接口​

  • 接口路径：/system/dict-data
  • 主要能力：
    • 新增：POST /create
    • 修改：PUT /update
    • 删除：DELETE /delete
    • 简单列表：GET /list-all-simple 或 /simple-list（仅启用）
    • 分页查询：GET /page
    • 详情查询：GET /get
    • 导出：GET /export
  • 权限控制：system:dict:create/update/query/delete/export 等。
  • 分页机制：同上，导出时设置 PAGE_SIZE_NONE。
  • 查询条件：分页请求对象包含字典类型筛选字段（具体字段以 VO 类为准）。

Mermaid Diagram Code:

flowchart TD
Start(["请求进入"]) --> Add["POST /create"]
Start --> Edit["PUT /update"]
Start --> Remove["DELETE /delete"]
Start --> SimpleList["GET /list-all-simple"]
Start --> Page["GET /page"]
Start --> Detail["GET /get"]
Start --> Export["GET /export"]
Add --> End(["返回结果"])
Edit --> End
Remove --> End
SimpleList --> End
Page --> End
Detail --> End
Export --> End

图表来源

章节来源

App端字典接口​

  • 接口路径：/system/dict-data/type
  • 主要能力：按字典类型查询启用状态的字典数据列表。
  • 访问控制：PermitAll，无需鉴权。
  • 查询条件：type（字典类型）必填。

Mermaid Diagram Code:

sequenceDiagram
participant App as "App客户端"
participant Ctrl as "AppDictDataController"
participant Rpc as "DictDataApi"
App->>Ctrl : "GET /system/dict-data/type?type=xxx"
Ctrl->>Rpc : "RPC查询字典数据"
Rpc-->>Ctrl : "返回字典列表"
Ctrl-->>App : "返回字典列表"

图表来源

章节来源

RPC字典接口​

  • 接口路径前缀：/dict-data
  • 主要能力：
    • 校验字典数据有效性：GET /valid
    • 获取指定字典数据：GET /get
    • 解析字典数据：GET /parse
    • 获取指定类型字典列表：GET /list
    • 默认方法：getDictDataLabel、getDictDataLabelList
  • 参数与返回：参见 DTO 与接口定义。

Mermaid Diagram Code:

classDiagram
class DictDataApi {
+validateDictDataList(dictType, values)
+getDictData(dictType, value)
+parseDictData(dictType, label)
+getDictDataList(dictType)
+getDictDataLabel(type, value)
+getDictDataLabelList(dictType)
}
class DictDataRespDTO {
+String label
+String value
+String dictType
+Integer status
}
DictDataApi --> DictDataRespDTO : "返回"

图表来源

章节来源

操作日志接口​

  • 接口路径：/system/operate-log
  • 主要能力：
    • 分页查询：GET /page
    • 导出Excel：GET /export
  • 权限控制：system:operate-log:query/export
  • 分页机制：同上，导出时设置 PAGE_SIZE_NONE。
  • 翻译增强：导出时对响应进行翻译处理。

Mermaid Diagram Code:

sequenceDiagram
participant Admin as "管理员"
participant Ctrl as "OperateLogController"
Admin->>Ctrl : "GET /system/operate-log/page"
Ctrl-->>Admin : "返回分页结果"
Admin->>Ctrl : "GET /system/operate-log/export"
Ctrl-->>Admin : "下载Excel文件"

图表来源

章节来源

API访问/异常日志接口​

  • API访问日志接口路径：/infra/api-access-log
  • 主要能力：
    • 分页查询：GET /page
    • 导出Excel：GET /export-excel
  • 权限控制：infra:api-access-log:query/export
  • 用户信息增强：通过 AdminUserApi 获取用户名与昵称并回填。
  • RPC接口：
    • ApiAccessLogApi：POST /api-access-log/create（同步/异步）
    • ApiErrorLogApi：POST /api-error-log/create（同步/异步）

Mermaid Diagram Code:

sequenceDiagram
participant Admin as "管理员"
participant Ctrl as "ApiAccessLogController"
participant Rpc as "ApiAccessLogApi/ApiErrorLogApi"
Admin->>Ctrl : "GET /infra/api-access-log/page"
Ctrl->>Rpc : "RPC查询日志"
Rpc-->>Ctrl : "返回日志列表"
Ctrl-->>Admin : "返回分页结果"
Admin->>Ctrl : "GET /infra/api-access-log/export-excel"
Ctrl-->>Admin : "下载Excel文件"

图表来源

章节来源

依赖关系分析​

  • 控制器依赖服务层（Service），服务层再依赖数据访问层（DAO/DO）。
  • App端字典接口通过 DictDataApi 进行RPC调用，实现跨模块解耦。
  • 日志接口通过 ApiAccessLogApi/ApiErrorLogApi 进行RPC写入，避免直接耦合存储实现。

Mermaid Diagram Code:

graph LR
AdminCtrl["DictTypeController/DictDataController"] --> Service["DictTypeService/DictDataService"]
AppCtrl["AppDictDataController"] --> Rpc["DictDataApi"]
OperateCtrl["OperateLogController"] --> OperateService["OperateLogService"]
AccessCtrl["ApiAccessLogController"] --> AccessApi["ApiAccessLogApi"]
AccessCtrl --> ErrorApi["ApiErrorLogApi"]

图表来源

章节来源

性能考虑​

  • 字典缓存策略
    • 启用状态的字典数据可缓存于内存或Redis，减少频繁查询数据库。
    • 提供简单列表接口（如 /list-all-simple）便于前端或服务端批量加载缓存。
    • 对高频字典类型采用LRU或TTL策略，结合定时刷新与变更事件驱动失效。
  • 日志性能
    • API访问/异常日志通过RPC异步写入，避免阻塞主业务链路。
    • 导出时设置 PAGE_SIZE_NONE 获取全量，注意大体量导出的内存与网络压力，建议分批或异步任务导出。
  • 分页与查询
    • 使用 PageParam 进行分页，合理设置每页大小，避免超大数据集一次性返回。
    • 对字典类型与状态等常用筛选条件建立索引，提升查询效率。

[本节为通用性能建议，不直接分析具体文件]

故障排查指南​

  • 字典接口
    • 若App端无法获取字典数据，请确认字典类型是否存在且状态为启用。
    • 若管理后台导出失败，请检查分页参数与数据量，必要时调整导出逻辑。
  • 日志接口
    • 访问日志导出缺少用户名/昵称：确认 AdminUserApi 能正确返回用户映射。
    • 异常日志未入库：检查全局异常处理器是否触发 ApiErrorLogApi 的异步写入。
  • 权限问题
    • 管理后台接口需具备对应权限，如 system:dict:、infra:api-access-log:、system:operate-log:*。

章节来源

结论​

本文档梳理了字典管理与日志管理的核心API，明确了数据结构、查询条件与分页机制，并提供了缓存策略与性能优化建议。通过清晰的接口边界与RPC解耦，系统实现了高内聚低耦合的日志与字典能力，便于扩展与维护。

[本节为总结性内容，不直接分析具体文件]

附录​

字典数据结构与字段说明​

  • 字典类型字段（示例）
    • 字典名称：显示名称
    • 字典类型：唯一标识
    • 状态：启用/禁用
    • 备注：描述信息
  • 字典数据字段（示例）
    • 字典标签：展示文本
    • 字典键值：实际存储值
    • 字典排序：排序号
    • 状态：启用/禁用
    • 颜色类型/CSS样式：前端展示样式
    • 备注：描述信息

章节来源

日志字段定义​

  • API访问日志字段（示例）
    • 链路追踪编号、用户编号/类型、应用名
    • 请求方法/地址/参数、响应体、用户IP/UserAgent
    • 模块/名称/分类、开始/结束时间、执行时长、结果码/消息
  • API异常日志字段（示例）
    • 链路追踪编号、用户编号/类型、应用名
    • 请求方法/地址/参数、用户IP/UserAgent
    • 异常时间/名称/类名/文件/方法/行号、异常栈、根因消息/消息

章节来源

查询条件与分页机制​

  • 分页参数：PageParam，导出场景设置 PAGE_SIZE_NONE 获取全量。
  • 字典类型/数据：支持按类型、状态等条件筛选。
  • 日志查询：支持按用户、应用名、时间范围、执行时长、结果码等条件筛选。

章节来源

字典缓存策略与日志审计要求​

  • 字典缓存
    • 缓存启用状态的字典数据，提供简单列表接口批量加载。
    • 变更时失效缓存，确保数据一致性。
  • 日志审计
    • 访问日志记录关键行为与性能指标。
    • 异常日志保留完整堆栈与上下文，便于定位问题。
    • 导出与翻译增强，满足合规与审计需求。

章节来源

用户文档
AI 助手
Agent 列表
请选择一个 Agent 开始对话
AI 问答