统一API框架架构说明书文档需求

介绍

Unify框架核心价值为‘整合异构能力、统一 API 入口、全链路安全可控、可视化运维治理’，助力企业快速构建标准化、高可用的 API 集成开发平台。Unify框架是一个ESB风格的统一RestAPI框架，包含unify-common、unify-crud、unify-api、unify-camel、unify-cloud五个核心模块，为开发者提供统一的数据访问接口、CRUD操作能力和异构集成能力。整体模块分为基础层（unify-common）→ 数据层（unify-crud）→ 集成层（unify-camel）→ 治理层（unify-cloud）→ 入口层（unify-api），为企业级应用提供全链路支撑。

graph TD
    A[unify-api] --> B[unify-crud]
    A[unify-api] --> C[unify-camel]
    B --> D[unify-common]
    B --> E[unify-cloud]
    C --> D[unify-common]
    C --> E[unify-cloud]

unify-common提供常见的工具类，如分布式Id、excel操作、文件上传/下载接口和service封装、统一消息中心、统一的数据推送和同步、缓存工具、分布式锁、序列化/反序列化工具;提供企业级应用的安全特性, 如属性配置加密、JWT token校验、AK/SK算法、端对端加密、WAF常见安全封装（请求频率限制、SQL 注入防护（CRUD DSL 层校验）、XSS/CSRF 防护、防重放攻击（基于nonce + 时间戳））；其他特性如controller日志AOP、service层日志AOP、统一返回结果封装、数据校验工具（支持自定义校验规则、多语言提示、嵌套校验；支持 API 入参自动校验）、统一异常处理、日志脱敏（支持自定义脱敏字段）、多环境配置隔离、异常重试等功能。封装操作审计日志（记录接口调用人 / 时间 / 操作 / 结果），基于标准加密算法实现审计日志完整性保护，支持合规查询。

unify-crud提供数据库crud接口的统一封装，提供crud xml dsl语法对常见的数据库操作进行抽象，开发人员可以通过自定义的dsl语法完成crud接口的配置，实现对crud接口层的安全控制。crud dsl操作支持基础的增删改查、条件查询（如范围、模糊、IN）、联表查询、批量操作;支持数据权限控制和crud缓存增强;支持多数据源动态切换。crud dsl规范详细见[../../../docs/crud_dsl.md]

unify-camel提供apache camel框架的封装，可以通过apache camel xml语法定义动态加载apache camel接口，支持rest、rabbitmq、ftp、webservice等常见协议，支持字段映射（不同协议报文字段映射）、格式转换（JSON/XML/Protobuf 互转）、数据清洗（空值处理 / 格式标准化）、多版本报文适配，快速完成接口配置开发。

unify-cloud集成zipkin、spring cloud stream、nacos、openfeign、cloud loadbalance等云原生开发能力，支持统一的服务配置和服务管理。集成基于 Resilience4j 的熔断限流机制，规则可通过 Nacos 动态配置，支持接口级 / 服务级限流熔断。Zipkin 链路追踪能力可贯穿 unify-api→unify-camel→unify-crud 全链路，基于 unify-common 封装的 TraceId 实现上下文统一传递。

unify-api集成unify-crud、unify-camel、unify-cloud提供统一的api接口，接口报文和格式遵循rest api接口格式。通过接口中动态传递的资源名称来定位唯一的资源，结合常见的crud接口提供统一的资源操作接口，实现统一的api接口。整体功能包括接口版本管理、OpenAPI 文档、统一鉴权增强、接口限流、接口防重放攻击（基于nonce + 时间戳），集成spring boot admin轻量的运维界面（接口管理、配置管理、监控查看、日志检索、多渠道告警推送），提供Prometheus监控指标。

术语表

• Unify框架: ESB风格的统一API框架，提供标准化的数据访问接口
• ESB: Enterprise Service Bus，企业服务总线架构模式
• CRUD: Create、Read、Update、Delete、数据导入、数据导出操作
• DSL: Domain Specific Language，领域特定语言，用于制定CRUD数据操作规范
• XML配置: 基于XML的声明式配置方式，用于配置CRUD数据操作
• 多租户: 支持多个租户共享同一应用实例的架构模式
• 动态表名: 根据业务规则动态确定数据库表名的机制

需求

需求 1

用户故事: 作为开发人员，我希望有一份完整的架构说明书文档，以便我能够理解Unify框架的整体架构和各模块职责。

验收标准

1. WHEN 开发人员查阅文档 THEN 系统SHALL提供框架整体架构概述和设计理念说明
2. WHEN 开发人员需要了解模块结构 THEN 系统SHALL详细描述三个核心模块的职责和依赖关系
3. WHEN 开发人员查看技术栈 THEN 系统SHALL列出所有主要技术组件和版本信息
4. WHEN 开发人员需要部署指导 THEN 系统SHALL提供环境要求和部署步骤说明
5. WHEN 开发人员遇到问题 THEN 系统SHALL提供常见问题解答和故障排除指南

需求 2

用户故事: 作为架构师，我希望文档能详细说明框架的核心功能和特性，以便我能够评估框架是否适合项目需求。

验收标准

1. WHEN 架构师评估框架能力 THEN 系统SHALL详细描述统一API接口的设计和实现方式
2. WHEN 架构师了解数据访问 THEN 系统SHALL说明动态CRUD操作和XML DSL配置机制
3. WHEN 架构师关注扩展性 THEN 系统SHALL描述框架的可扩展性设计和插件机制
4. WHEN 架构师考虑性能 THEN 系统SHALL提供性能特性和优化建议
5. WHEN 架构师评估安全性 THEN 系统SHALL说明安全机制和数据保护措施

需求 3

用户故事: 作为新团队成员，我希望文档提供清晰的使用指南和示例，以便我能够快速上手使用框架。

验收标准

1. WHEN 新成员开始使用框架 THEN 系统SHALL提供快速开始指南和基础配置示例
2. WHEN 新成员配置CRUD操作 THEN 系统SHALL提供XML DSL配置的详细语法说明和示例
3. WHEN 新成员开发API THEN 系统SHALL提供统一API接口的使用方法和最佳实践
4. WHEN 新成员需要定制功能 THEN 系统SHALL提供扩展开发指南和代码示例
5. WHEN 新成员遇到错误 THEN 系统SHALL提供调试方法和错误处理指导

需求 4

用户故事: 作为运维人员，我希望文档包含运维相关的信息，以便我能够有效地监控和维护框架。

验收标准

1. WHEN 运维人员部署应用 THEN 系统SHALL提供详细的部署配置和环境要求说明
2. WHEN 运维人员监控系统 THEN 系统SHALL说明监控指标和健康检查机制
3. WHEN 运维人员处理故障 THEN 系统SHALL提供日志配置和故障诊断方法
4. WHEN 运维人员进行维护 THEN 系统SHALL提供备份恢复和升级指导
5. WHEN 运维人员优化性能 THEN 系统SHALL提供性能调优建议和配置参数说明

文档结构

• CRUD DSL语法文档 - 详细的CRUD XML DSL配置语法和示例
• 构建系统文档 - Maven构建配置和安全实践指南
• CRUD接口文档 - 数据库CRUD通用接口说明

此文档由kiro生成