后端开发核心知识图谱

---

一、架构设计

概念	定义	核心要点	典型实现/工具
分层架构	按职责垂直划分代码层次	Controller → Service → Repository → DB；依赖单向向下；便于测试与替换	DDD 分层、Clean Architecture、六边形架构
微服务架构	按业务能力拆分为独立部署单元	服务自治、独立数据库、API 通信；引入分布式复杂度	Spring Cloud、Go-Micro、Kubernetes
单体架构	所有功能打包为单一部署单元	开发简单、部署容易；扩展性差、耦合度高	早期项目、快速验证
SOA	面向服务架构，服务通过 ESB 通信	企业级集成、服务复用；ESB 成为瓶颈	MuleSoft、IBM ESB
Serverless	函数即服务，按调用计费	免运维、自动伸缩；冷启动延迟、调试困难	AWS Lambda、Cloudflare Workers、Vercel
事件驱动架构	通过事件解耦生产者与消费者	异步处理、松耦合；事件溯源、最终一致性	Kafka、RabbitMQ、EventBridge
CQRS	命令查询职责分离	读写模型独立优化；复杂度换性能	Axon Framework、自研
领域驱动设计 (DDD)	以业务领域为核心建模	限界上下文、聚合根、领域事件、防腐层	战略设计 + 战术设计模式

---

二、高可用与容错

概念	定义	核心要点	典型实现/工具
限流 (Rate Limiting)	控制单位时间请求量	保护后端资源、防止雪崩；令牌桶、漏桶、滑动窗口算法	Sentinel、Nginx limit_req、Redis + Lua
熔断 (Circuit Breaker)	检测故障后快速失败，阻止级联崩溃	三态：关闭→打开→半开；失败率/慢调用率阈值触发	Hystrix、Resilience4j、Sentinel
降级 (Degradation)	服务不可用时返回兜底响应	静态数据、缓存数据、简化功能；保证核心链路	业务代码实现、配置中心动态开关
重试 (Retry)	失败后自动重新请求	指数退避、最大次数限制、幂等性保证	gRPC 内置、Resilience4j、自研
超时控制	限制等待时间，防止资源占用	连接超时、读写超时、全链路超时传递	Context timeout (Go)、Hystrix timeout
隔离 (Bulkhead)	资源隔离防止故障扩散	线程池隔离、信号量隔离、进程隔离	Hystrix、Resilience4j
故障注入	主动制造故障测试系统韧性	延迟注入、异常注入、资源耗尽	Chaos Monkey、ChaosBlade、LitmusChaos
健康检查	持续探测服务存活与就绪状态	Liveness vs Readiness；自动摘除故障节点	K8s Probe、Consul Health Check

---

三、分布式系统

概念	定义	核心要点	典型实现/工具
分布式锁	跨进程/节点的互斥控制	原子性、可重入、锁续期、防死锁	Redis (Redlock)、ZooKeeper、etcd
分布式事务	跨服务/库的数据一致性	2PC/3PC 强一致（阻塞）；TCC/Saga 最终一致	Seata、DTM、业务补偿
分布式 ID	全局唯一 ID 生成	趋势递增、高性能、无单点	Snowflake、Leaf、UUID v7
一致性哈希	数据分片与负载均衡	虚拟节点减少数据倾斜；节点增减影响最小化	自研、Ketama
CAP 定理	一致性、可用性、分区容错三选二	P 必选；CP (ZK) vs AP (Cassandra)；实际是权衡	理论指导
BASE 理论	基本可用、软状态、最终一致	CAP 的工程妥协；适用于高可用场景	电商、社交系统设计
Paxos/Raft	分布式共识算法	Leader 选举、日志复制、多数派	etcd (Raft)、ZooKeeper (ZAB)
服务注册与发现	动态管理服务实例地址	心跳检测、健康剔除、负载均衡	Consul、Nacos、etcd、Eureka
配置中心	集中管理配置，动态下发	版本管理、灰度发布、热更新	Apollo、Nacos、Consul KV
链路追踪	追踪跨服务请求调用链	TraceID/SpanID 传递；延迟分析、故障定位	Jaeger、Zipkin、SkyWalking
分布式日志	集中采集、存储、检索日志	结构化日志、全文检索、告警	ELK、Loki + Grafana、ClickHouse

---

四、数据库与存储

概念	定义	核心要点	典型实现/工具
快慢 SQL	识别执行时间异常的 SQL	慢查询日志、执行计划分析 (EXPLAIN)；索引优化	pt-query-digest、MySQL slow_log
索引优化	加速数据检索	B+Tree、覆盖索引、联合索引最左匹配；避免索引失效	EXPLAIN、索引建议工具
读写分离	主库写、从库读分担压力	主从延迟容忍、强制主库读；数据同步	MySQL Replication、ProxySQL
分库分表	水平拆分数据	路由策略（Hash/Range）、跨库查询、分布式事务	ShardingSphere、Vitess、TiDB
连接池	复用数据库连接	避免频繁建连；最小/最大连接数、空闲超时	HikariCP、Druid、pgbouncer
死锁	多事务相互等待资源	超时检测、死锁图；减小事务粒度、统一加锁顺序	DB 内置检测、应用层预防
事务隔离级别	并发事务可见性控制	RU/RC/RR/Serializable；脏读/不可重复读/幻读	数据库配置
MVCC	多版本并发控制	快照读、版本链；无锁读提高并发	MySQL InnoDB、PostgreSQL
缓存穿透	查询不存在数据，穿透到 DB	布隆过滤器、空值缓存	Redis + BloomFilter
缓存击穿	热点 key 失效瞬间高并发击穿	互斥锁、永不过期 + 后台刷新	Redis + 分布式锁
缓存雪崩	大量 key 同时失效	过期时间随机化、多级缓存、预热	运维策略
缓存一致性	缓存与 DB 数据同步	Cache Aside、Write Through、Write Behind；延迟双删	业务代码 + MQ
数据库连接泄漏	连接未正确归还连接池	超时强制回收、代码 Review、监控告警	连接池监控

---

五、消息队列

概念	定义	核心要点	典型实现/工具
异步解耦	生产者消费者通过队列交互	削峰填谷、系统解耦；引入延迟与复杂度	Kafka、RabbitMQ、RocketMQ
消息可靠投递	确保消息不丢失	生产者确认、Broker 持久化、消费者 ACK	发送重试、手动 ACK
消息幂等	重复消费不影响业务正确性	唯一 ID + 去重表/Redis；业务天然幂等	业务层实现
消息顺序性	保证消费顺序与发送一致	单分区有序；分区键设计	Kafka Partition Key
死信队列 (DLQ)	存放处理失败的消息	问题排查、人工干预、定期重试	RabbitMQ DLX、Kafka DLQ Topic
延迟消息	定时投递消息	订单超时取消、定时任务	RocketMQ 延迟级别、RabbitMQ TTL+DLX
消息堆积	消费速度跟不上生产速度	扩容消费者、降级、临时存储	监控告警 + 自动扩缩容
事务消息	本地事务与消息发送原子性	半消息 + 回查机制	RocketMQ 事务消息

---

六、安全

概念	定义	核心要点	典型实现/工具
认证 (AuthN)	验证身份 "你是谁"	密码、Token、证书、生物特征	JWT、OAuth2、OIDC、LDAP
授权 (AuthZ)	验证权限 "你能做什么"	RBAC、ABAC、ACL；最小权限原则	Casbin、OPA、Spring Security
SQL 注入	恶意 SQL 拼接执行	参数化查询、ORM、输入校验	PreparedStatement、GORM
XSS	跨站脚本注入	输出编码、CSP、HttpOnly Cookie	模板引擎自动转义
CSRF	跨站请求伪造	Token 校验、SameSite Cookie、Referer 检查	框架内置中间件
敏感数据保护	加密存储与传输	AES/RSA 加密、脱敏显示、密钥管理	Vault、KMS、bcrypt
API 安全	接口防护	签名校验、时间戳防重放、IP 白名单	HMAC 签名、mTLS
日志脱敏	防止敏感信息泄露到日志	手机号/身份证/密码脱敏规则	日志框架插件

---

七、性能优化

概念	定义	核心要点	典型实现/工具
性能剖析 (Profiling)	定位 CPU/内存热点	火焰图、采样分析	pprof (Go)、async-profiler (Java)
JVM 调优	GC、堆内存优化	G1/ZGC 选择、GC 日志分析、内存泄漏排查	jstat、MAT、Arthas
连接池调优	优化 DB/HTTP 连接复用	合理设置 min/max、超时、泄漏检测	HikariCP 配置
批量处理	合并小请求减少开销	批量插入、批量查询、Pipeline	JDBC Batch、Redis Pipeline
异步化	非核心逻辑异步执行	减少 RT、提高吞吐；幂等与补偿	MQ、CompletableFuture、goroutine
预热	启动时加载热点数据	减少冷启动影响；缓存预热、JIT 预热	启动脚本、流量回放
零拷贝	减少内核态/用户态数据拷贝	sendfile、mmap；适用于大文件传输	Kafka、Nginx
对象池	复用昂贵对象	减少 GC 压力；sync.Pool (Go)、对象池库	框架内置或自研

---

八、可观测性

概念	定义	核心要点	典型实现/工具
Metrics (指标)	数值化系统状态	QPS、RT、错误率、饱和度；RED/USE 方法论	Prometheus、InfluxDB、Graphite
Logging (日志)	离散事件记录	结构化 JSON、级别控制、TraceID 关联	ELK、Loki、Fluentd
Tracing (追踪)	分布式调用链	Span 上下文传播、耗时分析	Jaeger、Zipkin、OpenTelemetry
Alerting (告警)	异常自动通知	阈值告警、趋势告警、告警收敛	Prometheus Alertmanager、PagerDuty
SLO/SLI/SLA	服务质量目标与度量	SLI 是指标、SLO 是目标、SLA 是合同	业务定义 + 监控落地
Dashboard	可视化监控面板	关键指标聚合、钻取分析	Grafana、Kibana

---

九、DevOps 与部署

概念	定义	核心要点	典型实现/工具
CI/CD	持续集成与持续部署	自动构建、测试、部署；快速反馈	Jenkins、GitLab CI、GitHub Actions
容器化	应用与依赖打包为镜像	环境一致性、快速启动、隔离性	Docker、containerd
容器编排	管理容器生命周期与调度	自动扩缩容、服务发现、滚动更新	Kubernetes、Docker Swarm
蓝绿部署	两套环境切换流量	快速回滚、零停机；资源成本翻倍	K8s + Ingress、负载均衡切换
金丝雀发布	小流量验证后逐步扩大	风险可控、灰度验证	Istio、Argo Rollouts
滚动发布	逐批替换实例	资源利用率高；回滚较慢	K8s Deployment
GitOps	以 Git 为唯一真相来源	声明式、版本化、自动同步	ArgoCD、Flux
Infrastructure as Code	代码化管理基础设施	可审计、可重复、版本控制	Terraform、Pulumi、Ansible

---

十、API 设计

概念	定义	核心要点	典型实现/工具
RESTful	资源化 HTTP API 设计	资源命名、HTTP 动词语义、状态码规范	OpenAPI/Swagger
gRPC	高性能 RPC 框架	Protobuf 序列化、HTTP/2、双向流	grpc-go、grpc-java
GraphQL	按需查询 API	单端点、客户端定义返回结构；N+1 问题	Apollo、gqlgen
API 版本管理	兼容性演进	URL 版本 (/v1/)、Header 版本、语义化版本	设计规范
幂等设计	重复请求结果一致	唯一请求 ID、状态机校验	业务层实现
分页	大数据集分批返回	offset/limit、cursor-based；深度分页优化	数据库 + API
错误处理规范	统一错误响应格式	错误码体系、国际化、堆栈隐藏	RFC 7807 Problem Details

---

十一、测试

概念	定义	核心要点	典型实现/工具
单元测试	最小粒度代码测试	Mock 依赖、高覆盖率、快速执行	JUnit、testify、Jest
集成测试	多组件协作测试	真实依赖或 TestContainers；数据隔离	TestContainers、Spring Test
端到端测试	模拟用户完整流程	覆盖核心链路；执行慢、维护成本高	Cypress、Playwright
契约测试	验证服务间接口契约	生产者/消费者驱动	Pact、Spring Cloud Contract
压力测试	验证系统极限性能	并发数、TPS、RT、错误率	JMeter、Locust、k6
混沌工程	生产环境故障实验	验证系统韧性、发现潜在问题	Chaos Monkey、ChaosBlade

---

十二、编码与设计原则

概念	定义	核心要点
SOLID	面向对象五大原则	S 单一职责、O 开闭、L 里氏替换、I 接口隔离、D 依赖倒置
DRY	Don't Repeat Yourself	消除重复代码；过度抽象反成负担
KISS	Keep It Simple, Stupid	简单设计优先；避免过早优化
YAGNI	You Aren't Gonna Need It	不实现不需要的功能
防御性编程	假设输入不可信	参数校验、边界检查、失败处理
代码审查	同行评审代码变更	知识共享、质量把关、规范统一

---

速查索引

flowchart TB
    subgraph 架构
    A1[分层/DDD] --> A2[微服务]
    A2 --> A3[事件驱动]
    end
    
    subgraph 高可用
    B1[限流] --> B2[熔断]
    B2 --> B3[降级]
    B3 --> B4[重试]
    end
    
    subgraph 分布式
    C1[分布式锁] --> C2[分布式事务]
    C2 --> C3[服务发现]
    C3 --> C4[链路追踪]
    end
    
    subgraph 数据层
    D1[读写分离] --> D2[分库分表]
    D2 --> D3[缓存策略]
    D3 --> D4[SQL优化]
    end
    
    subgraph 消息队列
    E1[异步解耦] --> E2[可靠投递]
    E2 --> E3[幂等消费]
    end
    
    subgraph 可观测性
    F1[Metrics] --> F2[Logging]
    F2 --> F3[Tracing]
    end

---

前端开发核心知识图谱

---

一、浏览器原理

概念	定义	核心要点	典型实现/工具
渲染流程	URL 到像素的完整过程	解析 HTML → 构建 DOM → 解析 CSS → 构建 CSSOM → 合成 Render Tree → Layout → Paint → Composite	Chrome DevTools Performance
重排 (Reflow)	布局变化触发重新计算几何属性	触发因素：尺寸/位置变化、DOM 增删、窗口 resize；代价高	批量 DOM 操作、DocumentFragment
重绘 (Repaint)	外观变化不影响布局	触发因素：颜色、背景、visibility；代价低于重排	合理使用 CSS 属性
合成层 (Compositing)	GPU 加速独立图层	transform/opacity 不触发重排重绘；will-change 提示	图层分析、避免层爆炸
事件循环 (Event Loop)	JS 单线程任务调度机制	宏任务 (setTimeout, I/O) → 微任务 (Promise, MutationObserver) → 渲染	理解执行顺序、避免阻塞
垃圾回收 (GC)	自动内存管理	标记清除、分代回收；内存泄漏排查	Memory 面板、Heap Snapshot
V8 引擎	Chrome/Node 的 JS 引擎	解释执行 + JIT 编译；Hidden Class、内联缓存优化	编写 JIT 友好代码
同源策略	浏览器安全沙箱	协议 + 域名 + 端口一致；限制跨域请求与 DOM 访问	CORS、代理、postMessage
存储机制	客户端数据持久化	Cookie (4KB, 自动发送)、localStorage (5MB)、sessionStorage、IndexedDB (大容量)	按场景选择存储方案
Service Worker	独立于页面的后台线程	离线缓存、推送通知、后台同步；拦截网络请求	Workbox、PWA

---

二、JavaScript 进阶

概念	定义	核心要点	典型实现/工具
闭包 (Closure)	函数访问定义时作用域	数据封装、私有变量；内存泄漏风险	模块模式、柯里化
原型链 (Prototype)	对象继承机制	__proto__ → prototype；属性查找链	Object.create、class 语法糖
this 绑定	函数执行上下文	默认绑定、隐式绑定、显式绑定 (call/apply/bind)、new 绑定；箭头函数继承外层	理解调用方式决定 this
Promise/async-await	异步流程控制	状态机 (pending → fulfilled/rejected)；链式调用、错误冒泡	Promise.all/race/allSettled
生成器 (Generator)	可暂停函数	yield 暂停、next() 恢复；迭代器协议	异步流程、无限序列
代理 (Proxy)	拦截对象操作	get/set/has/deleteProperty 等 trap；响应式原理基础	Vue3 响应式、数据校验
反射 (Reflect)	对象操作函数化	与 Proxy trap 一一对应；替代命令式操作	Reflect.get/set/has
模块系统	代码组织与复用	ES Modules (静态分析、Tree Shaking)、CommonJS (动态、Node)；循环依赖处理	import/export
WeakMap/WeakSet	弱引用集合	键必须是对象、不阻止 GC；缓存、私有数据	框架内部实现
尾调用优化	函数末尾调用无栈增长	严格模式下生效；递归优化	部分引擎支持

---

三、CSS 进阶

概念	定义	核心要点	典型实现/工具
盒模型	元素尺寸计算	content-box (默认) vs border-box；margin 塌陷	box-sizing: border-box
BFC (块级格式化上下文)	独立布局区域	触发条件：float、position、overflow、display；清除浮动、防止 margin 重叠	overflow: hidden
Flexbox	一维弹性布局	主轴/交叉轴、flex-grow/shrink/basis；对齐方式	现代布局首选
Grid	二维网格布局	行列定义、区域命名、隐式网格；复杂布局	grid-template-areas
层叠上下文 (Stacking Context)	z-index 生效范围	触发条件：z-index + position、opacity<1、transform；嵌套隔离	理解 z-index 失效原因
选择器优先级	样式冲突解决	!important > 内联 > ID > 类/属性/伪类 > 元素 > *	避免过度使用 !important
CSS 变量	自定义属性	--name: value、var(--name)；主题切换、动态样式	:root 定义全局变量
响应式设计	适配多端设备	媒体查询、相对单位 (rem, vw, %)、容器查询	mobile-first、断点设计
CSS-in-JS	JS 中编写样式	作用域隔离、动态样式、SSR 支持	styled-components、Emotion
CSS Modules	类名局部化	编译时生成唯一类名；避免全局污染	Webpack css-loader
动画性能	高性能动画实现	transform/opacity 优先；requestAnimationFrame；FLIP 技术	避免动画卡顿

---

四、框架核心原理

概念	定义	核心要点	典型实现/工具
虚拟 DOM (Virtual DOM)	JS 对象描述 UI 结构	跨平台、批量更新、Diff 算法减少真实 DOM 操作	React、Vue
Diff 算法	新旧虚拟 DOM 比较	同层比较、key 优化、类型不同直接替换	O(n) 时间复杂度
响应式系统	数据变化自动更新视图	Vue2 Object.defineProperty、Vue3 Proxy、依赖收集、派发更新	手动触发 vs 自动追踪
单向数据流	数据自顶向下传递	可预测性、调试友好；状态提升	React props、Flux 模式
双向绑定	视图与数据自动同步	语法糖 (v-model)、表单场景；本质仍是单向流	Vue v-model
组件生命周期	组件创建到销毁的钩子	挂载、更新、卸载；副作用管理	useEffect、onMounted
Hooks	函数组件的状态与副作用	复用逻辑、组合优于继承；规则约束 (顶层调用)	React Hooks、Vue Composition API
状态管理	跨组件共享状态	单一数据源、不可变更新、中间件扩展	Redux、Zustand、Pinia、Vuex
服务端渲染 (SSR)	服务器生成 HTML	SEO 友好、首屏快；水合 (Hydration)、状态同步	Next.js、Nuxt.js
静态生成 (SSG)	构建时生成静态页面	极致性能、CDN 缓存；增量再生成 (ISR)	Next.js、Astro、Gatsby
编译时优化	构建阶段性能优化	模板预编译、静态节点提升、Tree Shaking	Vue3 编译优化、Svelte

---

五、性能优化

概念	定义	核心要点	典型实现/工具
核心 Web 指标	Google 性能评估标准	LCP (最大内容绘制 <2.5s)、FID (首次输入延迟 <100ms)、CLS (累积布局偏移 <0.1)	Lighthouse、Web Vitals
首屏优化	加速首次可见内容	关键渲染路径、骨架屏、预渲染、SSR	Critical CSS、Preload
代码分割	按需加载代码块	路由分割、组件懒加载；减少初始包体积	dynamic import、React.lazy
Tree Shaking	移除未使用代码	ES Modules 静态分析；sideEffects 配置	Webpack、Rollup、esbuild
资源压缩	减少传输体积	Gzip/Brotli 压缩、图片压缩、代码 Minify	构建工具 + 服务器配置
图片优化	图片加载与渲染优化	现代格式 (WebP, AVIF)、响应式图片、懒加载、CDN	next/image、srcset
缓存策略	复用已下载资源	强缓存 (Cache-Control)、协商缓存 (ETag)；文件指纹	长期缓存 + 内容哈希命名
预加载/预连接	提前获取资源	preload (关键资源)、prefetch (未来需要)、preconnect (DNS)	link 标签、Resource Hints
虚拟滚动	只渲染可视区域	大列表性能；动态高度、滚动锚定	react-window、vue-virtual-scroller
防抖/节流	控制高频事件执行	防抖 (最后一次)、节流 (固定间隔)；scroll/resize/input	lodash、自实现
Web Worker	后台线程计算	不阻塞主线程；无 DOM 访问；postMessage 通信	大数据计算、加密
内存优化	避免内存泄漏与过度占用	事件监听清理、闭包引用、DOM 引用；定期审查	Memory 面板、堆快照

---

六、工程化

概念	定义	核心要点	典型实现/工具
模块打包	多文件合并与优化	入口分析、依赖图、代码转换、产物输出	Webpack、Rollup、esbuild、Vite
热更新 (HMR)	开发时局部刷新	保持状态、快速反馈；模块热替换 API	Webpack HMR、Vite HMR
Babel	JS 语法转换	新语法 → 旧语法；preset-env 按目标环境转换	@babel/preset-env
PostCSS	CSS 转换管道	Autoprefixer、CSS 嵌套、自定义插件	postcss.config.js
ESLint	JS/TS 静态检查	语法错误、风格规范、自动修复	eslint-config-xxx
Prettier	代码格式化	风格统一、减少争议；与 ESLint 配合	.prettierrc
Husky + lint-staged	Git 钩子自动化	提交前检查/格式化；增量处理	pre-commit
Monorepo	单仓多包管理	代码共享、统一版本、依赖提升	pnpm workspace、Turborepo、Nx
包管理	依赖安装与版本管理	lock 文件锁定版本；pnpm 硬链接节省空间	npm、yarn、pnpm
环境变量	构建时配置注入	区分 dev/staging/prod；敏感信息隔离	.env 文件、import.meta.env
Source Map	调试映射源码	生产环境控制暴露；hidden-source-map	构建工具配置

---

七、网络与通信

概念	定义	核心要点	典型实现/工具
HTTP/1.1 vs HTTP/2 vs HTTP/3	协议演进	HTTP/2 多路复用、头部压缩；HTTP/3 基于 QUIC、0-RTT	服务器配置、CDN
HTTPS/TLS	加密传输	非对称握手 + 对称加密；证书链验证	Let's Encrypt、强制 HTTPS
CORS	跨域资源共享	简单请求 vs 预检请求；Access-Control-* 头	服务端配置
Fetch API	现代网络请求	Promise 化、流式读取；AbortController 取消	替代 XMLHttpRequest
WebSocket	全双工长连接	实时通信、服务器推送；心跳保活、重连机制	Socket.io、原生 API
Server-Sent Events	服务器单向推送	文本协议、自动重连；比 WebSocket 轻量	EventSource
请求封装	统一请求处理	拦截器、重试、超时、取消、状态管理	Axios、ky、ofetch
GraphQL 客户端	按需查询数据	类型安全、缓存规范化	Apollo Client、urql
接口缓存	减少重复请求	SWR (stale-while-revalidate)、请求去重	SWR、TanStack Query
文件上传	大文件传输	分片上传、断点续传、进度监控	自研 + 对象存储

---

八、安全

概念	定义	核心要点	典型实现/工具
XSS (跨站脚本)	注入恶意脚本执行	存储型/反射型/DOM 型；输出编码、CSP	React 自动转义、DOMPurify
CSRF (跨站请求伪造)	伪造用户请求	Token 校验、SameSite Cookie、Origin 检查	CSRF Token
CSP (内容安全策略)	限制资源加载来源	script-src、style-src、img-src；阻止内联脚本	HTTP Header、meta 标签
Cookie 安全	防止 Cookie 窃取与滥用	HttpOnly (JS 不可读)、Secure (仅 HTTPS)、SameSite	合理配置属性
点击劫持	透明 iframe 诱骗点击	X-Frame-Options: DENY、CSP frame-ancestors	HTTP Header
敏感信息暴露	源码/配置泄露	环境变量区分、Source Map 保护、.env 不提交	gitignore、构建配置
依赖安全	第三方包漏洞	npm audit、Snyk 扫描；锁定版本、定期更新	Dependabot
子资源完整性 (SRI)	CDN 资源防篡改	script/link 标签 integrity 属性	构建工具生成

---

九、状态管理

概念	定义	核心要点	典型实现/工具
局部状态	组件内部状态	useState/useReducer；简单场景首选	框架内置
提升状态	共享状态提升到公共父组件	props 传递、逆向数据流；层级深时繁琐	组件设计模式
Context	跨层级状态传递	避免 props drilling；频繁更新性能问题	React Context、Vue provide/inject
外部状态库	全局状态管理	单一数据源、可预测更新、DevTools	Redux、Zustand、Pinia、MobX
原子化状态	最小粒度状态单元	按需订阅、减少不必要渲染	Jotai、Recoil
服务端状态	远程数据缓存	请求状态、缓存失效、乐观更新	TanStack Query、SWR
URL 状态	路由参数作为状态	可分享、书签、SEO；query/params 同步	路由库 + nuqs
表单状态	表单专用状态管理	校验、脏检查、提交状态	React Hook Form、Formik、VeeValidate
持久化状态	刷新后保留状态	localStorage/sessionStorage 同步	redux-persist、zustand middleware

---

十、测试

概念	定义	核心要点	典型实现/工具
单元测试	独立函数/组件测试	快速、隔离、高覆盖率	Jest、Vitest
组件测试	渲染与交互测试	模拟用户行为、断言 DOM 状态	Testing Library、Vue Test Utils
集成测试	多组件/模块协作测试	真实路由、状态管理；Mock API	MSW、Testing Library
端到端测试 (E2E)	模拟真实用户操作	浏览器自动化、完整流程验证；执行慢、维护成本高	Playwright、Cypress
视觉回归测试	检测 UI 变化	截图对比、像素差异；防止意外样式变更	Percy、Chromatic、Playwright
快照测试	序列化输出对比	组件输出快照；易产生噪音更新	Jest Snapshot
Mock 与 Stub	模拟依赖行为	API Mock、模块 Mock、Timer Mock	MSW、jest.mock、vi.mock
测试覆盖率	代码被测试比例	行覆盖、分支覆盖、函数覆盖；指标非目标	Istanbul、c8
测试金字塔	测试策略分层	单元测试多 → 集成测试中 → E2E 少；成本与信心权衡	设计原则
TDD/BDD	测试驱动/行为驱动开发	先写测试后实现；描述性测试用例	开发流程

---

十一、TypeScript 前端应用

概念	定义	核心要点	典型实现/工具
组件 Props 类型	定义组件入参	interface/type 声明；可选、默认值、children	React.FC、defineProps
事件类型	DOM 事件类型定义	React.MouseEvent、React.ChangeEvent；e.target 类型收窄	事件处理函数签名
Ref 类型	引用类型定义	useRef<HTMLInputElement>(null)；forwardRef 泛型	Ref 对象类型
泛型组件	可复用类型参数组件	列表组件、选择器组件；推断 item 类型	<T,>(props: Props<T>)
API 类型生成	后端接口类型自动化	OpenAPI → TypeScript；端到端类型安全	openapi-typescript、orval
严格空检查	null/undefined 安全	strictNullChecks；可选链、空值合并	tsconfig.json
路由类型安全	路由参数类型化	路径参数、查询参数类型推断	TanStack Router、typed routes
状态库类型	全局状态类型定义	Store 类型、Action 类型、Selector 类型	Zustand/Redux 泛型

---

十二、可访问性 (Accessibility/A11y)

概念	定义	核心要点	典型实现/工具
语义化 HTML	使用正确的 HTML 标签	header/nav/main/article/aside；屏幕阅读器友好	避免 div 滥用
ARIA 属性	增强元素可访问性	role、aria-label、aria-hidden、aria-live	自定义组件必备
键盘导航	完全键盘可操作	Tab 顺序、焦点管理、快捷键；tabindex	focus trap、roving tabindex
焦点管理	控制焦点位置	模态框焦点陷阱、路由跳转焦点重置	FocusScope、焦点恢复
颜色对比度	文字与背景对比	WCAG 2.1 AA 标准 (4.5:1)；工具检测	设计规范、检测工具
屏幕阅读器	视障用户辅助工具	朗读内容、导航结构；测试验证	VoiceOver、NVDA、JAWS
跳过链接	快速跳过重复导航	Skip to main content	页面顶部隐藏链接
表单可访问性	表单元素关联标签	label + for、错误提示关联、必填提示	aria-describedby
动态内容通知	异步更新告知用户	aria-live="polite/assertive"；状态变化播报	加载、成功、错误提示
自动化检测	A11y 问题扫描	静态检查、运行时检测；CI 集成	axe-core、eslint-plugin-jsx-a11y

---

十三、国际化 (i18n)

概念	定义	核心要点	典型实现/工具
文案提取	硬编码文案外置	JSON/YAML 资源文件；按语言分文件	手动或工具提取
翻译管理	多语言翻译协作	翻译平台集成、版本管理、缺失检测	Crowdin、Lokalise、Phrase
插值与格式化	动态内容替换	变量插值、复数处理、日期/数字格式化	ICU MessageFormat
语言检测	自动识别用户语言	navigator.language、Accept-Language、用户设置	优先级策略
语言切换	运行时切换语言	无刷新切换、持久化选择	Context + 状态管理
RTL 支持	从右到左语言	阿拉伯语、希伯来语；布局镜像、文字方向	dir="rtl"、CSS logical properties
日期时间	本地化日期格式	Intl.DateTimeFormat；时区处理	date-fns、Day.js
数字货币	本地化数字格式	Intl.NumberFormat；千分位、货币符号	内置 API
命名空间	翻译文件组织	按功能/页面拆分；按需加载	i18next namespace
伪本地化	测试翻译就绪	字符替换模拟长度变化；检测硬编码	pseudo-localization

---

十四、移动端与跨平台

概念	定义	核心要点	典型实现/工具
响应式 Web	一套代码适配多端	媒体查询、弹性布局、相对单位	CSS Grid/Flexbox
PWA	渐进式 Web 应用	离线可用、可安装、推送通知；Service Worker	Workbox、Web App Manifest
移动端适配	处理移动端特性	viewport meta、触摸事件、安全区域、软键盘	设备检测、CSS 适配
Hybrid App	Web 嵌入原生壳	WebView 容器、Bridge 通信；性能受限	Cordova、Capacitor
React Native	JS 驱动原生组件	跨 iOS/Android；原生模块扩展	Expo、RN CLI
Flutter	Dart 跨平台框架	自绘引擎、高性能；学习成本	Flutter SDK
小程序	平台封闭生态	微信/支付宝/字节；双线程架构、受限 API	Taro、uni-app
Electron	桌面跨平台	Chromium + Node；内存占用大	Electron Forge
Tauri	轻量桌面应用	Rust 后端、系统 WebView；体积小	Tauri CLI

---

十五、微前端

概念	定义	核心要点	典型实现/工具
应用拆分	按业务拆分独立子应用	独立开发、部署、技术栈无关	架构设计
路由分发	主应用路由到子应用	路由匹配、生命周期管理	single-spa、qiankun
样式隔离	防止样式冲突	Shadow DOM、CSS Modules、命名空间	框架内置或约定
JS 沙箱	防止全局变量污染	Proxy 沙箱、快照沙箱；严格隔离	qiankun sandbox
通信机制	子应用间数据交换	CustomEvent、全局状态、props 传递	EventBus、共享状态
资源加载	动态加载子应用资源	HTML Entry、JS Entry；预加载	import-html-entry
共享依赖	避免重复加载公共库	Module Federation、external、CDN	Webpack 5 MF
Module Federation	运行时模块共享	远程模块、共享依赖、版本协商	Webpack 5、Vite 插件

---

十六、设计系统与组件库

概念	定义	核心要点	典型实现/工具
设计 Token	设计决策原子变量	颜色、间距、字号、阴影；单一来源	CSS 变量、JSON Token
组件规范	组件 API 与行为定义	Props、事件、插槽、状态；一致性	设计文档
原子设计	组件分层方法论	Atoms → Molecules → Organisms → Templates → Pages	组织架构
Headless UI	无样式逻辑组件	行为与样式分离；最大灵活性	Radix UI、Headless UI
Storybook	组件开发与文档	独立开发、可视化测试、交互文档	Storybook 7/8
主题系统	多主题支持	亮色/暗色、品牌定制；CSS 变量切换	prefers-color-scheme
组件文档	使用说明与示例	Props 表格、代码示例、在线演示	Storybook、Docusaurus
变更日志	版本变更记录	破坏性变更、新增、修复；语义化版本	CHANGELOG.md、Changesets

---

十七、实时与协作

概念	定义	核心要点	典型实现/工具
WebSocket	全双工实时通信	心跳保活、断线重连、消息确认	Socket.io、原生 API
长轮询	兼容性实时方案	请求挂起等待响应；资源消耗大	降级方案
CRDT	无冲突复制数据类型	多端并发编辑、自动合并；最终一致	Yjs、Automerge
OT (操作变换)	协同编辑算法	操作转换解决冲突；中心化	Google Docs 原理
乐观更新	先更新 UI 后同步服务器	提升体验；失败回滚	TanStack Query mutation
在线状态	用户在线感知	Presence、光标位置、正在输入	实时服务集成
离线支持	断网可用	IndexedDB 存储、队列同步、冲突解决	Service Worker、Workbox

---

十八、性能监控与错误追踪

概念	定义	核心要点	典型实现/工具
性能指标采集	自动收集 Web Vitals	LCP、FID、CLS、TTFB、FCP	web-vitals 库
错误捕获	全局异常收集	window.onerror、unhandledrejection；错误边界	try-catch、Error Boundary
Source Map 解析	还原压缩代码堆栈	上传 Source Map 到监控平台	Sentry、Bugsnag
用户行为回放	重现用户操作	DOM 快照、事件录制；问题复现	LogRocket、FullStory
自定义埋点	业务事件追踪	页面曝光、点击、转化；数据分析	自研或第三方 SDK
性能预算	设定性能阈值	包体积、加载时间上限；CI 检测	bundlesize、Lighthouse CI
真实用户监控 (RUM)	生产环境性能数据	按设备/地区/网络分析；长尾问题	Sentry、Datadog RUM
合成监控	模拟访问检测	定时探测、基线对比；可用性监控	Lighthouse CI、Checkly

---

十九、构建与部署

概念	定义	核心要点	典型实现/工具
CI/CD	持续集成与部署	自动构建、测试、部署；快速反馈	GitHub Actions、GitLab CI
静态托管	纯静态资源部署	CDN 分发、边缘缓存；极致性能	Vercel、Netlify、Cloudflare Pages
容器化部署	Docker 镜像部署	环境一致性、可扩展	Docker + K8s
边缘渲染	CDN 边缘执行代码	低延迟、地理就近；受限运行时	Cloudflare Workers、Vercel Edge
预渲染	构建时生成静态页	SSG、ISR；SEO + 性能	Next.js、Nuxt、Astro
环境管理	多环境配置	dev/staging/production；环境变量隔离	.env 文件、平台配置
回滚机制	快速恢复旧版本	版本保留、一键回滚	部署平台内置
Feature Flag	功能开关控制	灰度发布、A/B 测试、紧急关闭	LaunchDarkly、Unleash

---

二十、架构模式

概念	定义	核心要点	典型实现/工具
组件化架构	UI 拆分为可复用组件	单一职责、props 驱动、组合优于继承	React/Vue 组件
容器/展示组件	逻辑与 UI 分离	容器处理数据、展示负责渲染；Hooks 后弱化	设计模式
Compound Components	组合式组件 API	隐式共享状态、灵活组合	Tabs、Accordion 组件
Render Props	函数作为 children	逻辑复用；被 Hooks 替代	旧模式
HOC (高阶组件)	组件增强函数	横切关注点复用；层级嵌套问题	withRouter、connect
Hooks 模式	逻辑复用首选	自定义 Hooks、组合简单	useXxx
Feature-Sliced Design	按功能切片架构	分层 + 切片；扩展性好	项目结构规范
Islands 架构	静态页面嵌入交互岛屿	极致性能、部分水合	Astro、Fresh
Streaming SSR	流式服务端渲染	分块传输、逐步显示	React 18 Streaming

---

速查索引

flowchart TB
    subgraph 浏览器与语言
    A1[渲染原理] --> A2[事件循环]
    A2 --> A3[JS 进阶]
    A3 --> A4[CSS 布局]
    end
    
    subgraph 框架与状态
    B1[虚拟 DOM] --> B2[响应式]
    B2 --> B3[状态管理]
    B3 --> B4[SSR/SSG]
    end
    
    subgraph 工程化
    C1[构建工具] --> C2[代码规范]
    C2 --> C3[测试策略]
    C3 --> C4[CI/CD]
    end
    
    subgraph 性能与安全
    D1[Core Web Vitals] --> D2[代码分割]
    D2 --> D3[缓存策略]
    D3 --> D4[XSS/CSRF]
    end
    
    subgraph 体验与质量
    E1[可访问性] --> E2[国际化]
    E2 --> E3[错误监控]
    E3 --> E4[性能监控]
    end
    
    subgraph 架构扩展
    F1[微前端] --> F2[跨平台]
    F2 --> F3[设计系统]
    F3 --> F4[实时协作]
    end

---

前后端结合开发核心知识图谱

以 Spring Boot / Gin + Vue / React + TypeScript 为技术栈

---

一、接口设计与契约

概念	定义	核心要点	Spring Boot 实现	Gin 实现	前端实现
RESTful 规范	资源化 API 设计	名词复数、HTTP 动词语义、状态码规范	@GetMapping("/users/{id}")	r.GET("/users/:id", handler)	fetch/axios 调用
接口版本管理	API 兼容性演进	URL 路径 (/v1/)、Header、Query	@RequestMapping("/api/v1")	v1 := r.Group("/api/v1")	baseURL 配置
请求响应结构	统一数据格式	{code, data, message} 包装；分页结构	ResponseEntity<Result<T>>	自定义 Response 结构体	泛型 ApiResponse<T>
OpenAPI/Swagger	接口文档规范	自动生成文档、类型导出、Mock	springdoc-openapi	swaggo/swag	openapi-typescript 生成类型
接口幂等性	重复请求安全	幂等 Token、唯一请求 ID、状态机	拦截器 + Redis	中间件 + Redis	请求头携带幂等 Key
字段校验	入参合法性检查	非空、长度、正则、自定义规则	@Valid + Hibernate Validator	binding tag + validator/v10	zod/yup + 表单库
错误码体系	业务错误分类	模块前缀 + 错误编号；国际化	枚举 + 异常处理器	错误码常量 + 中间件	错误码映射提示文案

---

二、认证与授权

概念	定义	核心要点	Spring Boot 实现	Gin 实现	前端实现
JWT 认证	无状态 Token 认证	Header 携带、过期刷新、签名验证	jjwt + Filter	jwt-go + 中间件	请求拦截器自动携带
Token 刷新	无感续期	双 Token (Access + Refresh)；静默刷新	刷新接口 + Token 存储	刷新接口	响应拦截器 401 重试
OAuth2/OIDC	第三方登录	授权码流程、社交登录	Spring Security OAuth2	goth/golang-oauth2	重定向 + 回调处理
RBAC 权限	角色基础访问控制	用户-角色-权限；资源鉴权	@PreAuthorize	Casbin 中间件	路由守卫 + 按钮权限指令
权限数据同步	前端获取权限列表	登录后返回权限集；动态菜单	用户信息接口包含权限	同左	存储权限、动态路由生成
多租户	SaaS 数据隔离	租户 ID 透传、数据过滤	拦截器注入 TenantContext	中间件注入 Context	Header 携带租户标识
Session 管理	登录态控制	单点登录、踢人下线、并发控制	Spring Session + Redis	Redis 存储 Session	被踢时 WebSocket 通知

---

三、数据交互模式

概念	定义	核心要点	Spring Boot 实现	Gin 实现	前端实现
请求/响应	标准同步交互	RESTful CRUD；超时处理	RestController	gin.Context JSON	axios/fetch
分页查询	大数据集分批	offset/limit 或 cursor；总数可选	Pageable + Page<T>	GORM Scopes	分页组件 + 无限滚动
批量操作	多条数据一次处理	批量创建/更新/删除；事务保证	@RequestBody List<T>	切片入参	选中项批量提交
文件上传	二进制数据传输	multipart/form-data；大小限制	MultipartFile	c.FormFile	FormData + 进度监听
文件下载	文件流返回	Content-Disposition；断点续传	StreamingResponseBody	c.File / c.DataFromReader	Blob + download 属性
导入导出	Excel/CSV 处理	模板下载、异步导出、进度通知	EasyExcel / Apache POI	excelize	文件上传 + 结果轮询
GraphQL	按需查询	单端点、客户端定义返回结构	graphql-java / DGS	gqlgen / graphql-go	Apollo Client / urql
tRPC	端到端类型安全 RPC	自动类型推导、无需代码生成	不适用	不适用	tRPC + Next.js

---

四、实时通信

概念	定义	核心要点	Spring Boot 实现	Gin 实现	前端实现
WebSocket	全双工长连接	心跳保活、断线重连、房间管理	Spring WebSocket / STOMP	gorilla/websocket / melody	原生 API / Socket.io-client
SSE	服务端单向推送	轻量级、自动重连；文本协议	SseEmitter	c.Stream + SSE 格式	EventSource
消息广播	多客户端推送	发布订阅模式；集群广播	Redis Pub/Sub + WebSocket	Redis Pub/Sub	订阅 Topic
在线状态	用户 Presence	心跳检测、状态同步	Redis 记录 + 定时清理	同左	在线列表订阅
通知推送	系统消息下发	未读计数、消息中心	存储 + WebSocket/SSE	同左	通知组件 + 角标

---

五、类型安全与代码生成

概念	定义	核心要点	Spring Boot 实现	Gin 实现	前端实现
OpenAPI 类型生成	后端接口 → TS 类型	自动同步、减少手写	springdoc 生成 openapi.json	swag 生成 swagger.json	openapi-typescript / orval
DTO 定义	数据传输对象	请求/响应分离、字段裁剪	@Data class XxxDTO	结构体 + json tag	interface / type
枚举同步	前后端枚举一致	状态码、类型等	枚举类 + 接口暴露	const + 接口	生成或手动维护
校验规则同步	前后端校验一致	减少不一致导致体验差	Validator 注解	binding tag	zod schema 对应后端
Mock 数据	前端独立开发	契约先行、并行开发	文档导出	文档导出	MSW / Faker.js
端到端类型	全链路类型推导	零手写类型、自动同步	不直接支持	不直接支持	tRPC / ts-rest

---

六、状态同步

概念	定义	核心要点	Spring Boot 实现	Gin 实现	前端实现
乐观更新	先更新 UI 后同步	提升体验；失败回滚	接口正常响应	同左	TanStack Query mutation
悲观更新	等待响应再更新	数据准确；体验略差	接口返回最新数据	同左	默认行为
缓存失效	数据变更后刷新	手动失效、自动失效	无直接关联	无直接关联	queryClient.invalidateQueries
轮询	定时拉取数据	简单可靠；实时性差	普通接口	普通接口	refetchInterval
WebSocket 同步	服务端推送变更	实时性好；复杂度高	变更时广播	变更时广播	收到消息刷新 Query
冲突处理	并发编辑冲突	版本号检测、最后写入胜出	@Version 乐观锁	版本字段校验	冲突提示 + 合并 UI

---

七、错误处理

概念	定义	核心要点	Spring Boot 实现	Gin 实现	前端实现
全局异常处理	统一捕获处理异常	返回标准错误格式；日志记录	@ControllerAdvice	Recovery 中间件 + 自定义	响应拦截器
业务异常	可预期业务错误	自定义异常类、错误码	继承 RuntimeException	自定义 error 类型	根据 code 分支处理
参数校验错误	入参不合法	返回字段级错误信息	MethodArgumentNotValidException	binding.Validator 错误	表单字段错误映射
网络错误	请求失败	超时、断网、DNS 失败	后端无感知	后端无感知	错误边界 + 重试 UI
HTTP 状态码	标准错误语义	4xx 客户端错误、5xx 服务端	ResponseEntity	c.AbortWithStatusJSON	拦截器分类处理
错误上报	异常信息收集	堆栈、上下文、用户信息	Sentry SDK	Sentry SDK	Sentry / 自研 SDK
友好提示	用户可理解的错误	技术错误转用户文案；国际化	错误消息配置	错误消息映射	错误码 → 文案映射

---

八、安全协作

概念	定义	核心要点	Spring Boot 实现	Gin 实现	前端实现
CORS 配置	跨域资源共享	允许源、方法、头部；预检缓存	WebMvcConfigurer	cors 中间件	开发代理 / 生产同源
CSRF 防护	跨站请求伪造	Token 校验；SameSite Cookie	Spring Security CSRF	gorilla/csrf	表单携带 Token
XSS 防护	跨站脚本	输出编码、CSP 头	模板自动转义	html/template 转义	React/Vue 自动转义
SQL 注入防护	恶意 SQL 执行	参数化查询、ORM	JPA / MyBatis #{}	GORM 参数绑定	无直接关联
敏感数据脱敏	隐私保护	手机号、身份证、银行卡	序列化脱敏注解	自定义 MarshalJSON	展示层格式化
请求签名	防篡改防重放	timestamp + nonce + sign	拦截器验签	中间件验签	请求拦截器加签
HTTPS 强制	加密传输	HSTS 头；HTTP 重定向	server.ssl 配置	TLS 配置	确保请求走 HTTPS
速率限制	防止滥用	IP/用户维度限流	Bucket4j / Resilience4j	rate limiter 中间件	429 状态码处理

---

九、文件与资源

概念	定义	核心要点	Spring Boot 实现	Gin 实现	前端实现
静态资源托管	前端产物部署	CDN、缓存策略、版本哈希	分离部署 / static 目录	分离部署 / Static 中间件	构建产物部署到 CDN
上传预签名	直传对象存储	后端生成签名 URL、前端直传	AWS SDK / MinIO	AWS SDK / MinIO	获取签名 → PUT 上传
图片处理	缩放、裁剪、水印	CDN 处理 / 后端处理	Thumbnailator	imaging	拼接处理参数 URL
大文件分片	断点续传	分片上传、合并、进度	分片接口 + 合并	分片接口 + 合并	切片 + 并行上传
资源权限	私有资源访问	签名 URL、过期时间	生成临时访问 URL	生成临时访问 URL	动态获取访问链接
富文本/图片	内容中的资源	上传后替换 URL；防盗链	上传接口	上传接口	编辑器插件集成

---

十、异步任务

概念	定义	核心要点	Spring Boot 实现	Gin 实现	前端实现
异步接口	立即返回任务 ID	长耗时任务；轮询/回调获取结果	@Async + 任务存储	goroutine + 任务存储	提交 → 轮询进度
任务进度	实时反馈进度	百分比、阶段、预估时间	Redis 存储进度	Redis 存储进度	轮询 / SSE / WebSocket
任务取消	中止进行中任务	检查取消标志、资源清理	Future.cancel	context.WithCancel	调用取消接口
任务历史	任务执行记录	状态、耗时、结果、日志	任务表记录	任务表记录	任务列表页
定时任务	计划执行	Cron 表达式；分布式锁防重	@Scheduled + ShedLock	gocron + 分布式锁	管理界面配置
消息队列	异步解耦	削峰、重试、死信	RabbitMQ / Kafka	同左	无直接交互

---

十一、日志与追踪

概念	定义	核心要点	Spring Boot 实现	Gin 实现	前端实现
请求日志	记录请求响应	方法、路径、状态、耗时	Logbook / 拦截器	Logger 中间件	请求拦截器日志
TraceID 透传	全链路追踪标识	跨服务传递、日志关联	MDC + Header 传递	Context + Header	请求头携带 TraceID
前端日志上报	客户端日志收集	错误、行为、性能	日志接收接口	日志接收接口	SDK 采集上报
用户行为追踪	操作记录	点击、曝光、停留；埋点方案	日志或消息队列存储	同左	埋点 SDK
审计日志	敏感操作记录	谁在何时做了什么；不可篡改	AOP + 审计表	中间件 + 审计表	审计日志查看页
链路可视化	调用链展示	Span 关系、耗时分析	Spring Cloud Sleuth	OpenTelemetry	Jaeger / Zipkin UI

---

十二、缓存策略

概念	定义	核心要点	Spring Boot 实现	Gin 实现	前端实现
HTTP 缓存	浏览器/CDN 缓存	Cache-Control、ETag、Last-Modified	响应头设置	c.Header 设置	自动遵循
接口数据缓存	减少重复请求	SWR 策略、缓存时间	后端无感知	后端无感知	TanStack Query / SWR
服务端缓存	热点数据缓存	Redis 缓存、本地缓存	@Cacheable	go-cache / Redis	无直接交互
缓存预热	启动时加载	减少冷启动影响	InitializingBean	init 函数	预请求关键数据
缓存更新	数据一致性	Cache Aside、Write Through	手动失效	手动失效	invalidateQueries
离线缓存	断网可用	Service Worker 缓存策略	无关	无关	Workbox / CacheStorage

---

十三、测试协作

概念	定义	核心要点	Spring Boot 实现	Gin 实现	前端实现
契约测试	接口契约验证	生产者/消费者驱动	Spring Cloud Contract	Pact-go	Pact / MSW
Mock Server	模拟后端接口	前端独立开发测试	WireMock	不直接需要	MSW / json-server
E2E 测试	全链路集成测试	真实前后端联调	TestContainers	TestContainers	Playwright / Cypress
接口自动化	API 测试用例	回归测试、CI 集成	RestAssured	httptest	Postman / Newman
数据准备	测试数据构造	隔离、可重复、清理	Testcontainers + SQL	Testcontainers + SQL	Faker.js + MSW
环境隔离	独立测试环境	数据隔离、配置隔离	Profile 配置	配置文件	环境变量切换

---

十四、部署架构

概念	定义	核心要点	Spring Boot 实现	Gin 实现	前端实现
前后端分离部署	独立部署独立扩展	静态资源 CDN、API 服务器	独立 JAR 部署	独立二进制部署	Vercel / Nginx / CDN
BFF 层	前端专属后端	聚合裁剪、协议转换	独立服务	独立服务	直接调用 BFF
API Gateway	统一入口	路由、鉴权、限流、监控	Spring Cloud Gateway	Kong / Traefik	请求经过网关
容器化	Docker 部署	镜像构建、编排	Dockerfile + Jib	Dockerfile 多阶段构建	Dockerfile / 纯静态部署
灰度发布	渐进式发布	流量分配、版本控制	K8s + Istio	同左	版本标识 + 特性开关
配置管理	动态配置	不重启更新、环境隔离	Nacos / Apollo	Viper + Nacos	环境变量 / 运行时配置
健康检查	存活就绪探测	K8s Probe、负载均衡剔除	Actuator /health	自定义 /health	无直接关联

---

十五、开发协作流程

概念	定义	核心要点	后端职责	前端职责
接口先行	先定义接口再开发	OpenAPI 定义、评审、冻结	编写并维护 API 文档	基于文档生成类型、Mock
并行开发	前后端同时开发	Mock 数据、契约驱动	提供接口文档	使用 MSW Mock
联调测试	真实接口对接	环境对齐、问题定位	提供测试环境	切换真实接口
代码评审	交叉 Review	接口变更、破坏性检查	API 变更重点 Review	请求逻辑 Review
版本协同	多版本兼容	语义化版本、废弃通知	版本号管理、兼容策略	适配多版本接口
问题定位	前后端协作排查	日志、TraceID、重现步骤	提供日志、TraceID 查询	提供请求信息、TraceID
变更通知	接口变更同步	Breaking Change 预警	变更文档、邮件通知	订阅变更、及时适配

---

十六、典型功能实现对照

功能	后端核心逻辑	前端核心逻辑
登录	校验凭证 → 生成 Token → 返回用户信息	表单提交 → 存储 Token → 跳转首页
登出	清除服务端 Session/Token 黑名单	清除本地 Token → 跳转登录
列表查询	分页查询 → 数据转换 → 返回	请求数据 → 渲染表格 → 分页控制
详情查看	主键查询 → 关联查询 → 返回	请求详情 → 渲染表单/详情页
新增	参数校验 → 业务校验 → 入库 → 返回 ID	表单校验 → 提交 → 成功提示/跳转
编辑	参数校验 → 存在校验 → 更新 → 返回	加载数据 → 修改 → 提交 → 刷新
删除	权限校验 → 逻辑/物理删除 → 返回	确认弹窗 → 请求 → 刷新列表
导入	解析文件 → 校验 → 批量入库 → 返回结果	选择文件 → 上传 → 展示结果
导出	查询数据 → 生成文件 → 返回流/URL	触发导出 → 下载文件/轮询进度
权限控制	接口鉴权 → 数据过滤	菜单/按钮/路由 权限判断
实时通知	事件触发 → WebSocket/SSE 推送	建立连接 → 监听消息 → 更新 UI
文件上传	接收文件 → 存储 → 返回 URL	选择文件 → 上传 → 获取 URL

---

十七、性能优化协作

优化点	后端措施	前端措施
接口响应慢	SQL 优化、缓存、异步	骨架屏、Loading 状态
数据量大	分页、游标、流式返回	虚拟滚动、分页加载
重复请求	幂等设计	防抖、请求取消、缓存
首屏加载	接口合并、预热	SSR/SSG、代码分割、预加载
带宽消耗	Gzip/Brotli、字段裁剪	图片压缩、懒加载
并发瓶颈	限流、队列、水平扩展	请求排队、错误重试
长连接资源	连接池、心跳优化	按需连接、自动重连

---

速查索引

flowchart TB
    subgraph 接口层
    A1[RESTful/GraphQL] --> A2[认证授权]
    A2 --> A3[参数校验]
    A3 --> A4[错误处理]
    end
    
    subgraph 数据层
    B1[请求响应] --> B2[分页/批量]
    B2 --> B3[文件处理]
    B3 --> B4[缓存策略]
    end
    
    subgraph 实时层
    C1[WebSocket] --> C2[SSE]
    C2 --> C3[状态同步]
    C3 --> C4[通知推送]
    end
    
    subgraph 安全层
    D1[CORS] --> D2[CSRF/XSS]
    D2 --> D3[签名验证]
    D3 --> D4[速率限制]
    end
    
    subgraph 工程层
    E1[类型生成] --> E2[契约测试]
    E2 --> E3[日志追踪]
    E3 --> E4[部署架构]
    end
    
    subgraph 协作层
    F1[接口先行] --> F2[并行开发]
    F2 --> F3[联调测试]
    F3 --> F4[问题定位]
    end

---

技术栈快速对照

层次	Spring Boot	Gin	React	Vue
路由	@RequestMapping	gin.RouterGroup	React Router	Vue Router
状态管理	无直接对应	无直接对应	Redux / Zustand	Pinia / Vuex
请求处理	@RequestBody / @PathVariable	c.ShouldBindJSON / c.Param	axios / fetch	axios / fetch
响应处理	ResponseEntity	c.JSON	响应拦截器	响应拦截器
参数校验	Hibernate Validator	validator/v10	zod / yup	zod / vee-validate
中间件/拦截器	Filter / Interceptor	gin.HandlerFunc	axios interceptor	axios interceptor
依赖注入	@Autowired / 构造注入	wire / 手动注入	Context / Props	provide / inject
ORM	JPA / MyBatis	GORM / sqlx	无直接对应	无直接对应
缓存	@Cacheable + Redis	go-cache / Redis	TanStack Query	TanStack Query / SWR
WebSocket	Spring WebSocket	gorilla/websocket	原生 / Socket.io	原生 / Socket.io
定时任务	@Scheduled	gocron	无直接对应	无直接对应
配置管理	application.yml	viper / env	.env / import.meta.env	.env / import.meta.env
日志	Logback / Log4j2	zap / logrus	console / Sentry	console / Sentry
测试	JUnit / MockMvc	testing / httptest	Jest / Vitest	Vitest / Vue Test Utils
API 文档	springdoc-openapi	swaggo/swag	自动生成类型	自动生成类型
构建工具	Maven / Gradle	go build	Vite / Webpack	Vite / Webpack
容器化	Jib / Dockerfile	Dockerfile	Dockerfile / 静态部署	Dockerfile / 静态部署

---

十八、通用功能模块对照

用户认证模块

sequenceDiagram
    autonumber
    participant U as 用户
    participant F as 前端
    participant B as 后端
    participant DB as 数据库

    U->>F: 输入账号密码
    F->>F: 表单校验 (zod/yup)
    F->>B: POST /api/auth/login
    B->>B: 参数校验
    B->>DB: 查询用户
    DB-->>B: 返回用户数据
    B->>B: 验证密码 (bcrypt)
    B->>B: 生成 JWT (Access + Refresh)
    B-->>F: 返回 Token + 用户信息
    F->>F: 存储 Token (内存/Storage)
    F->>U: 跳转首页
    
    Note over F,B: 后续请求
    F->>B: 请求携带 Authorization: Bearer {token}
    B->>B: 验证 Token
    B-->>F: 返回业务数据

环节	Spring Boot	Gin	React	Vue
密码加密	BCryptPasswordEncoder	bcrypt	无	无
Token 生成	jjwt / java-jwt	jwt-go / golang-jwt	无	无
Token 存储	无状态 / Redis 黑名单	无状态 / Redis 黑名单	zustand / localStorage	pinia / localStorage
请求拦截	Filter / Interceptor	JWT 中间件	axios interceptor	axios interceptor
401 处理	返回 401	返回 401	跳转登录 / 刷新 Token	跳转登录 / 刷新 Token

---

CRUD 列表模块

环节	Spring Boot	Gin	React	Vue
分页参数	Pageable (page, size, sort)	自定义 PageQuery 结构体	useQuery + 分页状态	useQuery + 分页状态
查询构建	Specification / QueryDSL	GORM Scopes / Where	无	无
数据转换	MapStruct / 手动转 DTO	结构体转换	直接使用 / 转换函数	直接使用 / 转换函数
响应结构	Page<T> → PageResult	自定义 PageResult	解构 data, total	解构 data, total
表格渲染	无	无	Ant Design Table	Element Plus Table
搜索筛选	@RequestParam	c.Query	表单状态 → 请求参数	表单状态 → 请求参数
排序	Sort 参数	ORDER BY 拼接	列头点击 → 参数	列头点击 → 参数

---

表单提交模块

环节	Spring Boot	Gin	React	Vue
前端校验	无	无	React Hook Form + zod	VeeValidate + zod
后端校验	@Valid + 注解	binding tag + validator	无	无
唯一性校验	数据库唯一约束 + 查询	数据库唯一约束 + 查询	异步校验 blur 触发	异步校验 blur 触发
乐观锁	@Version	version 字段	提交时携带 version	提交时携带 version
提交状态	无	无	mutation.isPending	mutation.isPending
成功处理	返回 ID / 实体	返回 ID / 实体	提示 + 跳转/刷新	提示 + 跳转/刷新
错误处理	返回字段错误	返回字段错误	映射到表单字段	映射到表单字段

---

十九、安全检查清单

检查项	后端检查	前端检查
认证	Token 签名验证、过期检查	Token 存储安全、自动续期
授权	接口权限、数据权限	路由守卫、按钮权限
输入校验	类型、长度、格式、业务规则	类型、长度、格式
SQL 注入	参数化查询、ORM	无直接风险
XSS	输出编码、CSP	框架自动转义、DOMPurify
CSRF	Token 校验、SameSite	同源策略、Token 携带
敏感数据	加密存储、脱敏返回	脱敏展示、禁止日志
文件上传	类型校验、大小限制、病毒扫描	类型校验、大小校验
速率限制	IP/用户维度限流	429 友好提示
日志安全	脱敏、防注入	无敏感信息上报
依赖安全	依赖扫描、及时更新	npm audit、依赖扫描
传输安全	HTTPS 强制、HSTS	HTTPS 请求

---

二十、常见问题排查

问题现象	可能原因	后端排查	前端排查
401 未授权	Token 过期/无效/缺失	检查 Token 解析日志	检查 Token 存储与携带
403 禁止访问	权限不足	检查权限配置与用户角色	检查权限数据是否同步
404 未找到	路由不匹配/资源不存在	检查路由注册	检查请求 URL
500 服务错误	后端异常	检查异常堆栈与日志	检查请求参数
跨域错误	CORS 配置问题	检查 CORS 配置	检查请求是否跨域
请求超时	接口慢/网络问题	检查接口耗时	检查网络与超时设置
数据不一致	缓存/并发问题	检查缓存与事务	检查本地缓存刷新
文件上传失败	大小限制/类型限制	检查配置与校验	检查文件类型与大小
WebSocket 断开	心跳/网络问题	检查连接日志	检查重连逻辑
页面白屏	JS 错误/接口失败	检查接口响应	检查控制台错误

---

二十一、接口设计最佳实践

实践	说明	示例
资源命名	名词复数、层级清晰	/users/{id}/orders
HTTP 动词	GET 查询、POST 创建、PUT 替换、PATCH 更新、DELETE 删除	PATCH /users/123
状态码语义	2xx 成功、4xx 客户端错误、5xx 服务端错误	201 Created、422 Unprocessable Entity
分页参数	page/size 或 cursor/limit	?page=1&size=20
过滤排序	查询参数表达	?status=active&sort=-createdAt
字段选择	按需返回字段	?fields=id,name,email
批量操作	专用端点或请求体数组	POST /users/batch
版本管理	URL 或 Header	/v1/users 或 Accept: application/vnd.api.v1+json
错误格式	统一结构	{code, message, details}
幂等设计	幂等 Key 或天然幂等	X-Idempotency-Key: uuid

---

二十二、前后端协作规范模板

接口文档模板

endpoint: POST /api/v1/users
summary: 创建用户
authentication: Bearer Token
request:
  headers:
    Content-Type: application/json
    Authorization: Bearer {token}
  body:
    name: string (required, 2-50 chars)
    email: string (required, email format)
    role: enum (admin | user | guest)
response:
  success:
    status: 201
    body:
      code: 0
      data:
        id: number
        name: string
        email: string
        createdAt: datetime
  errors:
    - status: 400
      code: 40001
      message: "参数校验失败"
      details: [{field: "email", message: "格式错误"}]
    - status: 409
      code: 40901
      message: "邮箱已存在"

错误码规范

范围	模块	示例
10000-19999	通用错误	10001 参数错误
20000-29999	用户模块	20001 用户不存在
30000-39999	订单模块	30001 订单已取消
40000-49999	支付模块	40001 余额不足
50000-59999	文件模块	50001 文件过大

Git 分支规范

main          # 生产分支
├── develop   # 开发分支
│   ├── feature/user-auth      # 功能分支
│   ├── feature/order-export   # 功能分支
│   └── fix/login-bug          # 修复分支
├── release/v1.2.0             # 发布分支
└── hotfix/payment-issue       # 热修复分支

提交信息规范

feat(user): 新增用户注册接口
fix(order): 修复订单金额计算错误
docs(api): 更新接口文档
refactor(auth): 重构认证中间件
test(user): 添加用户模块单元测试
chore(deps): 升级依赖版本

---

二十三、项目结构对照

Spring Boot 典型结构

src/main/java/com/example/
├── config/           # 配置类
├── controller/       # 控制器
├── service/          # 业务逻辑
│   └── impl/
├── repository/       # 数据访问
├── entity/           # 实体类
├── dto/              # 数据传输对象
│   ├── request/
│   └── response/
├── exception/        # 异常定义
├── util/             # 工具类
└── Application.java

Gin 典型结构

├── cmd/
│   └── server/
│       └── main.go
├── internal/
│   ├── handler/      # 请求处理
│   ├── service/      # 业务逻辑
│   ├── repository/   # 数据访问
│   ├── model/        # 数据模型
│   │   ├── entity/
│   │   ├── request/
│   │   └── response/
│   ├── middleware/   # 中间件
│   └── config/       # 配置
├── pkg/              # 公共包
└── go.mod

React 典型结构

src/
├── components/       # 通用组件
│   └── ui/
├── features/         # 功能模块
│   ├── auth/
│   │   ├── components/
│   │   ├── hooks/
│   │   ├── api.ts
│   │   └── types.ts
│   └── users/
├── hooks/            # 全局 Hooks
├── lib/              # 工具库
├── api/              # API 配置
├── types/            # 类型定义
├── stores/           # 状态管理
└── App.tsx

Vue 典型结构

src/
├── components/       # 通用组件
│   └── ui/
├── views/            # 页面组件
├── composables/      # 组合式函数
├── api/              # API 定义
├── types/            # 类型定义
├── stores/           # Pinia stores
├── router/           # 路由配置
├── utils/            # 工具函数
└── App.vue

---

速查索引（完整）

flowchart TB
    subgraph 接口设计
    A1[RESTful 规范] --> A2[版本管理]
    A2 --> A3[参数校验]
    A3 --> A4[错误码体系]
    end
    
    subgraph 认证授权
    B1[JWT 认证] --> B2[Token 刷新]
    B2 --> B3[RBAC 权限]
    B3 --> B4[会话管理]
    end
    
    subgraph 数据交互
    C1[CRUD] --> C2[分页/批量]
    C2 --> C3[文件处理]
    C3 --> C4[实时通信]
    end
    
    subgraph 类型安全
    D1[OpenAPI] --> D2[类型生成]
    D2 --> D3[DTO 同步]
    D3 --> D4[Mock 数据]
    end
    
    subgraph 安全协作
    E1[CORS] --> E2[CSRF/XSS]
    E2 --> E3[请求签名]
    E3 --> E4[速率限制]
    end
    
    subgraph 工程协作
    F1[接口先行] --> F2[并行开发]
    F2 --> F3[联调测试]
    F3 --> F4[部署架构]
    end

---

附录：大型工程典型项目结构

---

一、Spring Boot 大型工程结构

project-root/
├── pom.xml                                    # 父 POM（多模块管理）
├── docker-compose.yml                         # 本地开发环境
├── Dockerfile
├── Makefile
├── README.md
│
├── docs/                                      # 项目文档
│   ├── api/                                   # API 文档
│   ├── architecture/                          # 架构设计
│   └── database/                              # 数据库设计
│
├── deploy/                                    # 部署配置
│   ├── k8s/
│   │   ├── base/
│   │   ├── overlays/
│   │   │   ├── dev/
│   │   │   ├── staging/
│   │   │   └── prod/
│   └── scripts/
│
├── project-common/                            # 公共模块
│   ├── pom.xml
│   └── src/main/java/com/example/common/
│       ├── annotation/                        # 自定义注解
│       │   ├── Log.java
│       │   ├── RateLimit.java
│       │   └── RequirePermission.java
│       ├── constant/                          # 常量定义
│       │   ├── CommonConstant.java
│       │   ├── RedisKeyConstant.java
│       │   └── SecurityConstant.java
│       ├── enums/                             # 枚举定义
│       │   ├── ErrorCodeEnum.java
│       │   ├── StatusEnum.java
│       │   └── BusinessTypeEnum.java
│       ├── exception/                         # 异常定义
│       │   ├── BaseException.java
│       │   ├── BusinessException.java
│       │   ├── AuthenticationException.java
│       │   └── RateLimitException.java
│       ├── result/                            # 响应结构
│       │   ├── Result.java
│       │   ├── PageResult.java
│       │   └── ErrorDetail.java
│       └── util/                              # 工具类
│           ├── JsonUtils.java
│           ├── DateUtils.java
│           ├── SecurityUtils.java
│           ├── IpUtils.java
│           └── AssertUtils.java
│
├── project-core/                              # 核心模块
│   ├── pom.xml
│   └── src/main/java/com/example/core/
│       ├── config/                            # 核心配置
│       │   ├── SecurityConfig.java
│       │   ├── RedisConfig.java
│       │   ├── MybatisPlusConfig.java
│       │   ├── ThreadPoolConfig.java
│       │   ├── CorsConfig.java
│       │   └── OpenApiConfig.java
│       ├── filter/                            # 过滤器
│       │   ├── JwtAuthenticationFilter.java
│       │   ├── TraceIdFilter.java
│       │   └── XssFilter.java
│       ├── interceptor/                       # 拦截器
│       │   ├── RateLimitInterceptor.java
│       │   ├── PermissionInterceptor.java
│       │   └── TenantInterceptor.java
│       ├── aspect/                            # 切面
│       │   ├── LogAspect.java
│       │   ├── CacheAspect.java
│       │   └── DistributedLockAspect.java
│       ├── handler/                           # 处理器
│       │   ├── GlobalExceptionHandler.java
│       │   ├── MybatisMetaObjectHandler.java
│       │   └── SensitiveDataHandler.java
│       ├── security/                          # 安全组件
│       │   ├── JwtTokenProvider.java
│       │   ├── UserDetailsServiceImpl.java
│       │   └── PasswordEncoder.java
│       └── event/                             # 事件定义
│           ├── UserLoginEvent.java
│           └── OrderCreatedEvent.java
│
├── project-domain/                            # 领域模块
│   ├── pom.xml
│   └── src/main/java/com/example/domain/
│       │
│       ├── user/                              # 用户领域
│       │   ├── entity/
│       │   │   ├── User.java
│       │   │   ├── Role.java
│       │   │   └── Permission.java
│       │   ├── repository/
│       │   │   ├── UserRepository.java
│       │   │   └── RoleRepository.java
│       │   ├── service/
│       │   │   ├── UserService.java
│       │   │   ├── UserServiceImpl.java
│       │   │   ├── RoleService.java
│       │   │   └── RoleServiceImpl.java
│       │   ├── dto/
│       │   │   ├── request/
│       │   │   │   ├── UserCreateRequest.java
│       │   │   │   ├── UserUpdateRequest.java
│       │   │   │   └── UserQueryRequest.java
│       │   │   └── response/
│       │   │       ├── UserResponse.java
│       │   │       └── UserDetailResponse.java
│       │   ├── converter/
│       │   │   └── UserConverter.java
│       │   └── event/
│       │       ├── UserCreatedEvent.java
│       │       └── UserEventListener.java
│       │
│       ├── order/                             # 订单领域
│       │   ├── entity/
│       │   │   ├── Order.java
│       │   │   └── OrderItem.java
│       │   ├── repository/
│       │   ├── service/
│       │   ├── dto/
│       │   ├── converter/
│       │   ├── state/                         # 状态机
│       │   │   ├── OrderState.java
│       │   │   └── OrderStateMachine.java
│       │   └── saga/                          # 分布式事务
│       │       └── CreateOrderSaga.java
│       │
│       └── payment/                           # 支付领域
│           ├── entity/
│           ├── repository/
│           ├── service/
│           ├── dto/
│           ├── strategy/                      # 策略模式
│           │   ├── PaymentStrategy.java
│           │   ├── AlipayStrategy.java
│           │   └── WechatPayStrategy.java
│           └── callback/
│               └── PaymentCallbackHandler.java
│
├── project-api/                               # API 模块（对外暴露）
│   ├── pom.xml
│   └── src/main/java/com/example/api/
│       ├── controller/
│       │   ├── AuthController.java
│       │   ├── UserController.java
│       │   ├── OrderController.java
│       │   └── FileController.java
│       └── websocket/
│           ├── WebSocketConfig.java
│           └── NotificationWebSocketHandler.java
│
├── project-admin/                             # 管理后台模块
│   ├── pom.xml
│   └── src/main/java/com/example/admin/
│       └── controller/
│           ├── AdminUserController.java
│           ├── AdminOrderController.java
│           └── SystemConfigController.java
│
├── project-job/                               # 定时任务模块
│   ├── pom.xml
│   └── src/main/java/com/example/job/
│       ├── config/
│       │   └── QuartzConfig.java
│       └── task/
│           ├── OrderTimeoutTask.java
│           ├── DataSyncTask.java
│           └── ReportGenerateTask.java
│
├── project-integration/                       # 外部集成模块
│   ├── pom.xml
│   └── src/main/java/com/example/integration/
│       ├── sms/
│       │   ├── SmsClient.java
│       │   └── AliyunSmsClient.java
│       ├── oss/
│       │   ├── OssClient.java
│       │   └── MinioOssClient.java
│       ├── payment/
│       │   ├── AlipayClient.java
│       │   └── WechatPayClient.java
│       └── mq/
│           ├── producer/
│           │   └── OrderMessageProducer.java
│           └── consumer/
│               └── OrderMessageConsumer.java
│
└── project-boot/                              # 启动模块
    ├── pom.xml
    └── src/
        ├── main/
        │   ├── java/com/example/
        │   │   └── Application.java
        │   └── resources/
        │       ├── application.yml
        │       ├── application-dev.yml
        │       ├── application-staging.yml
        │       ├── application-prod.yml
        │       ├── logback-spring.xml
        │       └── db/
        │           └── migration/             # Flyway 迁移
        │               ├── V1__init.sql
        │               └── V2__add_order.sql
        └── test/
            └── java/com/example/
                ├── integration/               # 集成测试
                └── unit/                      # 单元测试

模块依赖关系

flowchart TB
    subgraph 启动层
    BOOT[project-boot]
    end
    
    subgraph 接口层
    API[project-api]
    ADMIN[project-admin]
    JOB[project-job]
    end
    
    subgraph 领域层
    DOMAIN[project-domain]
    end
    
    subgraph 基础设施层
    CORE[project-core]
    INTEGRATION[project-integration]
    end
    
    subgraph 公共层
    COMMON[project-common]
    end
    
    BOOT --> API
    BOOT --> ADMIN
    BOOT --> JOB
    API --> DOMAIN
    ADMIN --> DOMAIN
    JOB --> DOMAIN
    DOMAIN --> CORE
    DOMAIN --> INTEGRATION
    CORE --> COMMON
    INTEGRATION --> COMMON

---

二、Gin 大型工程结构

project-root/
├── go.mod
├── go.sum
├── Makefile
├── Dockerfile
├── docker-compose.yml
├── .golangci.yml                              # Lint 配置
├── .air.toml                                  # 热重载配置
├── README.md
│
├── docs/                                      # 项目文档
│   ├── swagger/                               # Swagger 文档
│   │   └── swagger.json
│   ├── api/
│   └── architecture/
│
├── deploy/                                    # 部署配置
│   ├── k8s/
│   │   ├── base/
│   │   └── overlays/
│   │       ├── dev/
│   │       ├── staging/
│   │       └── prod/
│   └── scripts/
│
├── cmd/                                       # 入口程序
│   ├── server/                                # API 服务
│   │   └── main.go
│   ├── admin/                                 # 管理后台
│   │   └── main.go
│   ├── worker/                                # 异步 Worker
│   │   └── main.go
│   ├── job/                                   # 定时任务
│   │   └── main.go
│   └── migrate/                               # 数据迁移
│       └── main.go
│
├── configs/                                   # 配置文件
│   ├── config.yaml
│   ├── config.dev.yaml
│   ├── config.staging.yaml
│   └── config.prod.yaml
│
├── internal/                                  # 内部包（不对外暴露）
│   │
│   ├── config/                                # 配置加载
│   │   ├── config.go
│   │   └── loader.go
│   │
│   ├── server/                                # HTTP 服务
│   │   ├── server.go
│   │   ├── router.go
│   │   └── middleware.go
│   │
│   ├── middleware/                            # 中间件
│   │   ├── auth.go
│   │   ├── cors.go
│   │   ├── logger.go
│   │   ├── recovery.go
│   │   ├── ratelimit.go
│   │   ├── trace.go
│   │   ├── tenant.go
│   │   └── permission.go
│   │
│   ├── handler/                               # 请求处理（按领域分组）
│   │   ├── handler.go                         # 公共 Handler
│   │   ├── auth/
│   │   │   ├── handler.go
│   │   │   ├── login.go
│   │   │   ├── logout.go
│   │   │   └── refresh.go
│   │   ├── user/
│   │   │   ├── handler.go
│   │   │   ├── create.go
│   │   │   ├── update.go
│   │   │   ├── delete.go
│   │   │   ├── get.go
│   │   │   └── list.go
│   │   ├── order/
│   │   │   ├── handler.go
│   │   │   ├── create.go
│   │   │   ├── cancel.go
│   │   │   └── list.go
│   │   └── file/
│   │       ├── handler.go
│   │       ├── upload.go
│   │       └── download.go
│   │
│   ├── service/                               # 业务逻辑
│   │   ├── auth/
│   │   │   ├── service.go
│   │   │   └── jwt.go
│   │   ├── user/
│   │   │   ├── service.go
│   │   │   └── password.go
│   │   ├── order/
│   │   │   ├── service.go
│   │   │   ├── state_machine.go
│   │   │   └── saga.go
│   │   └── payment/
│   │       ├── service.go
│   │       ├── alipay.go
│   │       └── wechat.go
│   │
│   ├── repository/                            # 数据访问
│   │   ├── repository.go                      # 仓储接口定义
│   │   ├── user/
│   │   │   ├── repository.go
│   │   │   ├── repository_impl.go
│   │   │   └── cache.go
│   │   ├── order/
│   │   │   ├── repository.go
│   │   │   └── repository_impl.go
│   │   └── cache/
│   │       ├── redis.go
│   │       └── local.go
│   │
│   ├── model/                                 # 数据模型
│   │   ├── entity/                            # 数据库实体
│   │   │   ├── base.go
│   │   │   ├── user.go
│   │   │   ├── role.go
│   │   │   ├── order.go
│   │   │   └── payment.go
│   │   ├── request/                           # 请求结构
│   │   │   ├── common.go
│   │   │   ├── auth.go
│   │   │   ├── user.go
│   │   │   └── order.go
│   │   ├── response/                          # 响应结构
│   │   │   ├── common.go
│   │   │   ├── user.go
│   │   │   └── order.go
│   │   └── converter/                         # 结构转换
│   │       ├── user.go
│   │       └── order.go
│   │
│   ├── job/                                   # 定时任务
│   │   ├── scheduler.go
│   │   ├── order_timeout.go
│   │   └── data_sync.go
│   │
│   ├── worker/                                # 异步任务
│   │   ├── worker.go
│   │   ├── order_worker.go
│   │   └── notification_worker.go
│   │
│   ├── event/                                 # 事件
│   │   ├── dispatcher.go
│   │   ├── user_event.go
│   │   └── order_event.go
│   │
│   └── integration/                           # 外部集成
│       ├── sms/
│       │   ├── client.go
│       │   └── aliyun.go
│       ├── oss/
│       │   ├── client.go
│       │   └── minio.go
│       ├── mq/
│       │   ├── producer.go
│       │   └── consumer.go
│       └── payment/
│           ├── alipay.go
│           └── wechat.go
│
├── pkg/                                       # 公共包（可对外暴露）
│   ├── errors/                                # 错误处理
│   │   ├── errors.go
│   │   ├── codes.go
│   │   └── wrap.go
│   ├── logger/                                # 日志
│   │   ├── logger.go
│   │   └── zap.go
│   ├── database/                              # 数据库
│   │   ├── mysql.go
│   │   ├── postgres.go
│   │   └── migration.go
│   ├── cache/                                 # 缓存
│   │   └── redis.go
│   ├── utils/                                 # 工具函数
│   │   ├── crypto.go
│   │   ├── time.go
│   │   ├── string.go
│   │   ├── validate.go
│   │   └── ip.go
│   ├── response/                              # 响应封装
│   │   ├── response.go
│   │   └── page.go
│   ├── jwt/                                   # JWT
│   │   └── jwt.go
│   ├── lock/                                  # 分布式锁
│   │   └── redis_lock.go
│   ├── trace/                                 # 链路追踪
│   │   └── trace.go
│   └── pagination/                            # 分页
│       └── pagination.go
│
├── migrations/                                # 数据库迁移
│   ├── 000001_init.up.sql
│   ├── 000001_init.down.sql
│   ├── 000002_add_order.up.sql
│   └── 000002_add_order.down.sql
│
├── scripts/                                   # 脚本
│   ├── build.sh
│   ├── test.sh
│   └── generate.sh
│
├── api/                                       # API 定义（可选 protobuf）
│   └── v1/
│       ├── user.proto
│       └── order.proto
│
└── test/                                      # 测试
    ├── integration/
    │   ├── user_test.go
    │   └── order_test.go
    ├── e2e/
    │   └── api_test.go
    └── mock/
        ├── user_repository_mock.go
        └── order_service_mock.go

包依赖关系

flowchart TB
    subgraph 入口层
    CMD[cmd/*]
    end
    
    subgraph 接口层
    HANDLER[internal/handler]
    MIDDLEWARE[internal/middleware]
    SERVER[internal/server]
    end
    
    subgraph 业务层
    SERVICE[internal/service]
    JOB[internal/job]
    WORKER[internal/worker]
    EVENT[internal/event]
    end
    
    subgraph 数据层
    REPO[internal/repository]
    MODEL[internal/model]
    end
    
    subgraph 集成层
    INTEGRATION[internal/integration]
    end
    
    subgraph 基础层
    PKG[pkg/*]
    CONFIG[internal/config]
    end
    
    CMD --> SERVER
    SERVER --> HANDLER
    SERVER --> MIDDLEWARE
    HANDLER --> SERVICE
    MIDDLEWARE --> PKG
    SERVICE --> REPO
    SERVICE --> INTEGRATION
    SERVICE --> EVENT
    REPO --> MODEL
    REPO --> PKG
    JOB --> SERVICE
    WORKER --> SERVICE
    INTEGRATION --> PKG
    CONFIG --> PKG

---

三、React 大型工程结构

project-root/
├── package.json
├── pnpm-workspace.yaml                        # Monorepo 配置
├── turbo.json                                 # Turborepo 配置
├── tsconfig.json
├── .eslintrc.js
├── .prettierrc
├── .env.example
├── docker-compose.yml
├── Dockerfile
├── README.md
│
├── docs/                                      # 项目文档
│   ├── architecture/
│   ├── components/
│   └── conventions/
│
├── deploy/                                    # 部署配置
│   ├── nginx/
│   │   └── nginx.conf
│   └── k8s/
│
├── packages/                                  # Monorepo 包
│   │
│   ├── ui/                                    # UI 组件库
│   │   ├── package.json
│   │   ├── tsconfig.json
│   │   ├── src/
│   │   │   ├── components/
│   │   │   │   ├── Button/
│   │   │   │   │   ├── Button.tsx
│   │   │   │   │   ├── Button.test.tsx
│   │   │   │   │   ├── Button.stories.tsx
│   │   │   │   │   └── index.ts
│   │   │   │   ├── Input/
│   │   │   │   ├── Modal/
│   │   │   │   ├── Table/
│   │   │   │   ├── Form/
│   │   │   │   └── index.ts
│   │   │   ├── hooks/
│   │   │   │   ├── useDisclosure.ts
│   │   │   │   └── useMediaQuery.ts
│   │   │   ├── styles/
│   │   │   │   ├── tokens.css
│   │   │   │   └── globals.css
│   │   │   └── index.ts
│   │   └── .storybook/
│   │
│   ├── shared/                                # 共享工具
│   │   ├── package.json
│   │   ├── src/
│   │   │   ├── utils/
│   │   │   │   ├── format.ts
│   │   │   │   ├── date.ts
│   │   │   │   ├── storage.ts
│   │   │   │   └── index.ts
│   │   │   ├── constants/
│   │   │   │   ├── routes.ts
│   │   │   │   ├── queryKeys.ts
│   │   │   │   └── index.ts
│   │   │   ├── types/
│   │   │   │   ├── common.ts
│   │   │   │   ├── api.ts
│   │   │   │   └── index.ts
│   │   │   └── index.ts
│   │   └── tsconfig.json
│   │
│   ├── api-client/                            # API 客户端
│   │   ├── package.json
│   │   ├── src/
│   │   │   ├── client.ts                      # Axios 实例
│   │   │   ├── interceptors/
│   │   │   │   ├── auth.ts
│   │   │   │   ├── error.ts
│   │   │   │   └── retry.ts
│   │   │   ├── generated/                     # OpenAPI 生成
│   │   │   │   ├── types.ts
│   │   │   │   └── services.ts
│   │   │   └── index.ts
│   │   ├── openapi.json                       # OpenAPI 规范
│   │   └── tsconfig.json
│   │
│   └── config/                                # 共享配置
│       ├── eslint/
│       ├── typescript/
│       └── tailwind/
│
├── apps/                                      # 应用
│   │
│   ├── web/                                   # 主应用
│   │   ├── package.json
│   │   ├── tsconfig.json
│   │   ├── vite.config.ts
│   │   ├── index.html
│   │   ├── public/
│   │   │   ├── favicon.ico
│   │   │   └── manifest.json
│   │   │
│   │   └── src/
│   │       ├── main.tsx                       # 入口
│   │       ├── App.tsx
│   │       ├── vite-env.d.ts
│   │       │
│   │       ├── app/                           # 应用配置
│   │       │   ├── providers/                 # Provider 组合
│   │       │   │   ├── AppProvider.tsx
│   │       │   │   ├── AuthProvider.tsx
│   │       │   │   ├── QueryProvider.tsx
│   │       │   │   └── ThemeProvider.tsx
│   │       │   ├── router/                    # 路由配置
│   │       │   │   ├── index.tsx
│   │       │   │   ├── routes.tsx
│   │       │   │   ├── guards/
│   │       │   │   │   ├── AuthGuard.tsx
│   │       │   │   │   └── PermissionGuard.tsx
│   │       │   │   └── layouts/
│   │       │   │       ├── MainLayout.tsx
│   │       │   │       ├── AuthLayout.tsx
│   │       │   │       └── DashboardLayout.tsx
│   │       │   └── config/
│   │       │       ├── env.ts
│   │       │       └── constants.ts
│   │       │
│   │       ├── features/                      # 功能模块（核心）
│   │       │   │
│   │       │   ├── auth/                      # 认证模块
│   │       │   │   ├── api/
│   │       │   │   │   ├── auth.api.ts
│   │       │   │   │   └── auth.types.ts
│   │       │   │   ├── components/
│   │       │   │   │   ├── LoginForm/
│   │       │   │   │   │   ├── LoginForm.tsx
│   │       │   │   │   │   ├── LoginForm.schema.ts
│   │       │   │   │   │   └── index.ts
│   │       │   │   │   └── RegisterForm/
│   │       │   │   ├── hooks/
│   │       │   │   │   ├── useAuth.ts
│   │       │   │   │   ├── useLogin.ts
│   │       │   │   │   └── useLogout.ts
│   │       │   │   ├── stores/
│   │       │   │   │   └── auth.store.ts
│   │       │   │   ├── pages/
│   │       │   │   │   ├── LoginPage.tsx
│   │       │   │   │   └── RegisterPage.tsx
│   │       │   │   ├── utils/
│   │       │   │   │   └── token.ts
│   │       │   │   └── index.ts
│   │       │   │
│   │       │   ├── users/                     # 用户模块
│   │       │   │   ├── api/
│   │       │   │   │   ├── users.api.ts
│   │       │   │   │   └── users.types.ts
│   │       │   │   ├── components/
│   │       │   │   │   ├── UserList/
│   │       │   │   │   ├── UserForm/
│   │       │   │   │   ├── UserDetail/
│   │       │   │   │   └── UserAvatar/
│   │       │   │   ├── hooks/
│   │       │   │   │   ├── useUsers.ts
│   │       │   │   │   ├── useUser.ts
│   │       │   │   │   ├── useCreateUser.ts
│   │       │   │   │   └── useUpdateUser.ts
│   │       │   │   ├── pages/
│   │       │   │   │   ├── UsersPage.tsx
│   │       │   │   │   ├── UserDetailPage.tsx
│   │       │   │   │   └── UserCreatePage.tsx
│   │       │   │   └── index.ts
│   │       │   │
│   │       │   ├── orders/                    # 订单模块
│   │       │   │   ├── api/
│   │       │   │   │   ├── orders.api.ts
│   │       │   │   │   └── orders.types.ts
│   │       │   │   ├── components/
│   │       │   │   │   ├── OrderList/
│   │       │   │   │   ├── OrderDetail/
│   │       │   │   │   ├── OrderForm/
│   │       │   │   │   ├── OrderStatusBadge/
│   │       │   │   │   └── OrderTimeline/
│   │       │   │   ├── hooks/
│   │       │   │   │   ├── useOrders.ts
│   │       │   │   │   ├── useOrder.ts
│   │       │   │   │   ├── useCreateOrder.ts
│   │       │   │   │   └── useCancelOrder.ts
│   │       │   │   ├── pages/
│   │       │   │   │   ├── OrdersPage.tsx
│   │       │   │   │   ├── OrderDetailPage.tsx
│   │       │   │   │   └── OrderCreatePage.tsx
│   │       │   │   └── index.ts
│   │       │   │
│   │       │   ├── dashboard/                 # 仪表盘模块
│   │       │   │   ├── api/
│   │       │   │   │   └── dashboard.api.ts
│   │       │   │   ├── components/
│   │       │   │   │   ├── StatCard/
│   │       │   │   │   ├── RevenueChart/
│   │       │   │   │   ├── RecentOrders/
│   │       │   │   │   └── UserGrowthChart/
│   │       │   │   ├── hooks/
│   │       │   │   │   └── useDashboardStats.ts
│   │       │   │   ├── pages/
│   │       │   │   │   └── DashboardPage.tsx
│   │       │   │   └── index.ts
│   │       │   │
│   │       │   ├── settings/                  # 设置模块
│   │       │   │   ├── api/
│   │       │   │   ├── components/
│   │       │   │   │   ├── ProfileForm/
│   │       │   │   │   ├── PasswordForm/
│   │       │   │   │   ├── NotificationSettings/
│   │       │   │   │   └── ThemeSettings/
│   │       │   │   ├── hooks/
│   │       │   │   ├── pages/
│   │       │   │   │   ├── SettingsPage.tsx
│   │       │   │   │   └── ProfilePage.tsx
│   │       │   │   └── index.ts
│   │       │   │
│   │       │   └── notifications/             # 通知模块
│   │       │       ├── api/
│   │       │       ├── components/
│   │       │       │   ├── NotificationList/
│   │       │       │   ├── NotificationItem/
│   │       │       │   └── NotificationBell/
│   │       │       ├── hooks/
│   │       │       │   ├── useNotifications.ts
│   │       │       │   └── useWebSocket.ts
│   │       │       ├── stores/
│   │       │       │   └── notification.store.ts
│   │       │       └── index.ts
│   │       │
│   │       ├── components/                    # 应用级通用组件
│   │       │   ├── ErrorBoundary/
│   │       │   │   ├── ErrorBoundary.tsx
│   │       │   │   └── ErrorFallback.tsx
│   │       │   ├── LoadingScreen/
│   │       │   ├── PageHeader/
│   │       │   ├── Sidebar/
│   │       │   ├── Navbar/
│   │       │   ├── Breadcrumb/
│   │       │   ├── ConfirmDialog/
│   │       │   ├── DataTable/
│   │       │   │   ├── DataTable.tsx
│   │       │   │   ├── DataTablePagination.tsx
│   │       │   │   ├── DataTableFilter.tsx
│   │       │   │   └── index.ts
│   │       │   ├── FileUpload/
│   │       │   └── RichTextEditor/
│   │       │
│   │       ├── hooks/                         # 应用级通用 Hooks
│   │       │   ├── useDebounce.ts
│   │       │   ├── useLocalStorage.ts
│   │       │   ├── usePagination.ts
│   │       │   ├── usePermission.ts
│   │       │   ├── useConfirm.ts
│   │       │   └── index.ts
│   │       │
│   │       ├── stores/                        # 全局状态
│   │       │   ├── index.ts
│   │       │   ├── ui.store.ts                # UI 状态（侧边栏、主题等）
│   │       │   └── permission.store.ts
│   │       │
│   │       ├── lib/                           # 第三方库封装
│   │       │   ├── axios.ts
│   │       │   ├── dayjs.ts
│   │       │   ├── i18n.ts
│   │       │   └── sentry.ts
│   │       │
│   │       ├── styles/                        # 全局样式
│   │       │   ├── globals.css
│   │       │   └── tailwind.css
│   │       │
│   │       └── types/                         # 应用类型定义
│   │           ├── global.d.ts
│   │           └── env.d.ts
│   │
│   ├── admin/                                 # 管理后台应用
│   │   ├── package.json
│   │   ├── tsconfig.json
│   │   ├── vite.config.ts
│   │   └── src/
│   │       ├── main.tsx
│   │       ├── features/
│   │       │   ├── system/                    # 系统管理
│   │       │   │   ├── components/
│   │       │   │   ├── pages/
│   │       │   │   │   ├── RoleManagePage.tsx
│   │       │   │   │   ├── MenuManagePage.tsx
│   │       │   │   │   └── DictManagePage.tsx
│   │       │   │   └── index.ts
│   │       │   ├── logs/                      # 日志管理
│   │       │   └── monitor/                   # 系统监控
│   │       └── ...
│   │
│   └── mobile/                                # 移动端 H5
│       ├── package.json
│       └── src/
│           └── ...
│
├── tools/                                     # 工具脚本
│   ├── generators/                            # 代码生成器
│   │   ├── feature/
│   │   │   └── index.ts
│   │   └── component/
│   │       └── index.ts
│   └── scripts/
│       ├── generate-api.ts                    # 生成 API 类型
│       └── analyze-bundle.ts
│
└── tests/                                     # E2E 测试
    ├── e2e/
    │   ├── auth.spec.ts
    │   ├── users.spec.ts
    │   └── orders.spec.ts
    ├── fixtures/
    └── playwright.config.ts

Feature 模块内部结构详解

flowchart TB
    subgraph Feature Module
        API[api/] --> |定义| TYPES[types]
        API --> |请求| HOOKS[hooks/]
        HOOKS --> |数据| PAGES[pages/]
        HOOKS --> |数据| COMPONENTS[components/]
        STORES[stores/] --> |状态| COMPONENTS
        STORES --> |状态| PAGES
        COMPONENTS --> |组合| PAGES
        UTILS[utils/] --> |工具| HOOKS
        UTILS --> |工具| COMPONENTS
    end

---

四、Vue 大型工程结构

project-root/
├── package.json
├── pnpm-workspace.yaml                        # Monorepo 配置
├── turbo.json
├── tsconfig.json
├── .eslintrc.js
├── .prettierrc
├── .env.example
├── docker-compose.yml
├── Dockerfile
├── README.md
│
├── docs/                                      # 项目文档
│   ├── architecture/
│   ├── components/
│   └── conventions/
│
├── deploy/                                    # 部署配置
│   ├── nginx/
│   │   └── nginx.conf
│   └── k8s/
│
├── packages/                                  # Monorepo 包
│   │
│   ├── ui/                                    # UI 组件库
│   │   ├── package.json
│   │   ├── tsconfig.json
│   │   ├── vite.config.ts
│   │   ├── src/
│   │   │   ├── components/
│   │   │   │   ├── Button/
│   │   │   │   │   ├── Button.vue
│   │   │   │   │   ├── Button.test.ts
│   │   │   │   │   ├── Button.story.vue
│   │   │   │   │   └── index.ts
│   │   │   │   ├── Input/
│   │   │   │   │   ├── Input.vue
│   │   │   │   │   └── index.ts
│   │   │   │   ├── Modal/
│   │   │   │   ├── Table/
│   │   │   │   ├── Form/
│   │   │   │   └── index.ts
│   │   │   ├── composables/
│   │   │   │   ├── useDisclosure.ts
│   │   │   │   └── useMediaQuery.ts
│   │   │   ├── directives/
│   │   │   │   ├── vFocus.ts
│   │   │   │   ├── vClickOutside.ts
│   │   │   │   └── index.ts
│   │   │   ├── styles/
│   │   │   │   ├── tokens.css
│   │   │   │   └── globals.css
│   │   │   └── index.ts
│   │   └── .storybook/
│   │
│   ├── shared/                                # 共享工具
│   │   ├── package.json
│   │   ├── src/
│   │   │   ├── utils/
│   │   │   │   ├── format.ts
│   │   │   │   ├── date.ts
│   │   │   │   ├── storage.ts
│   │   │   │   ├── tree.ts                    # 树结构处理
│   │   │   │   └── index.ts
│   │   │   ├── constants/
│   │   │   │   ├── routes.ts
│   │   │   │   ├── queryKeys.ts
│   │   │   │   └── index.ts
│   │   │   ├── types/
│   │   │   │   ├── common.ts
│   │   │   │   ├── api.ts
│   │   │   │   └── index.ts
│   │   │   └── index.ts
│   │   └── tsconfig.json
│   │
│   ├── api-client/                            # API 客户端
│   │   ├── package.json
│   │   ├── src/
│   │   │   ├── client.ts
│   │   │   ├── interceptors/
│   │   │   │   ├── auth.ts
│   │   │   │   ├── error.ts
│   │   │   │   └── retry.ts
│   │   │   ├── generated/
│   │   │   │   ├── types.ts
│   │   │   │   └── services.ts
│   │   │   └── index.ts
│   │   ├── openapi.json
│   │   └── tsconfig.json
│   │
│   └── config/                                # 共享配置
│       ├── eslint/
│       ├── typescript/
│       └── unocss/
│
├── apps/                                      # 应用
│   │
│   ├── web/                                   # 主应用
│   │   ├── package.json
│   │   ├── tsconfig.json
│   │   ├── vite.config.ts
│   │   ├── index.html
│   │   ├── public/
│   │   │   ├── favicon.ico
│   │   │   └── manifest.json
│   │   │
│   │   └── src/
│   │       ├── main.ts                        # 入口
│   │       ├── App.vue
│   │       ├── env.d.ts
│   │       │
│   │       ├── app/                           # 应用配置
│   │       │   ├── plugins/                   # Vue 插件
│   │       │   │   ├── index.ts
│   │       │   │   ├── pinia.ts
│   │       │   │   ├── router.ts
│   │       │   │   ├── i18n.ts
│   │       │   │   └── query.ts               # Vue Query
│   │       │   ├── router/                    # 路由配置
│   │       │   │   ├── index.ts
│   │       │   │   ├── routes/
│   │       │   │   │   ├── index.ts
│   │       │   │   │   ├── auth.routes.ts
│   │       │   │   │   ├── user.routes.ts
│   │       │   │   │   └── order.routes.ts
│   │       │   │   ├── guards/
│   │       │   │   │   ├── auth.guard.ts
│   │       │   │   │   └── permission.guard.ts
│   │       │   │   └── helpers/
│   │       │   │       └── dynamic-routes.ts  # 动态路由
│   │       │   └── config/
│   │       │       ├── env.ts
│   │       │       └── constants.ts
│   │       │
│   │       ├── layouts/                       # 布局组件
│   │       │   ├── DefaultLayout/
│   │       │   │   ├── DefaultLayout.vue
│   │       │   │   ├── components/
│   │       │   │   │   ├── Sidebar.vue
│   │       │   │   │   ├── Navbar.vue
│   │       │   │   │   ├── Footer.vue
│   │       │   │   │   └── Breadcrumb.vue
│   │       │   │   └── index.ts
│   │       │   ├── AuthLayout/
│   │       │   │   └── AuthLayout.vue
│   │       │   └── BlankLayout/
│   │       │       └── BlankLayout.vue
│   │       │
│   │       ├── modules/                       # 功能模块（核心）
│   │       │   │
│   │       │   ├── auth/                      # 认证模块
│   │       │   │   ├── api/
│   │       │   │   │   ├── index.ts
│   │       │   │   │   └── types.ts
│   │       │   │   ├── components/
│   │       │   │   │   ├── LoginForm.vue
│   │       │   │   │   ├── RegisterForm.vue
│   │       │   │   │   └── ForgotPasswordForm.vue
│   │       │   │   ├── composables/
│   │       │   │   │   ├── useAuth.ts
│   │       │   │   │   ├── useLogin.ts
│   │       │   │   │   └── useLogout.ts
│   │       │   │   ├── stores/
│   │       │   │   │   └── auth.store.ts
│   │       │   │   ├── views/
│   │       │   │   │   ├── LoginView.vue
│   │       │   │   │   └── RegisterView.vue
│   │       │   │   └── index.ts
│   │       │   │
│   │       │   ├── user/                      # 用户模块
│   │       │   │   ├── api/
│   │       │   │   │   ├── index.ts
│   │       │   │   │   └── types.ts
│   │       │   │   ├── components/
│   │       │   │   │   ├── UserList/
│   │       │   │   │   │   ├── UserList.vue
│   │       │   │   │   │   ├── UserListItem.vue
│   │       │   │   │   │   ├── UserListFilter.vue
│   │       │   │   │   │   └── index.ts
│   │       │   │   │   ├── UserForm/
│   │       │   │   │   │   ├── UserForm.vue
│   │       │   │   │   │   ├── UserFormBasic.vue
│   │       │   │   │   │   ├── UserFormRole.vue
│   │       │   │   │   │   └── index.ts
│   │       │   │   │   ├── UserDetail/
│   │       │   │   │   └── UserAvatar/
│   │       │   │   ├── composables/
│   │       │   │   │   ├── useUsers.ts
│   │       │   │   │   ├── useUser.ts
│   │       │   │   │   ├── useCreateUser.ts
│   │       │   │   │   ├── useUpdateUser.ts
│   │       │   │   │   └── useDeleteUser.ts
│   │       │   │   ├── views/
│   │       │   │   │   ├── UserListView.vue
│   │       │   │   │   ├── UserDetailView.vue
│   │       │   │   │   └── UserFormView.vue
│   │       │   │   └── index.ts
│   │       │   │
│   │       │   ├── order/                     # 订单模块
│   │       │   │   ├── api/
│   │       │   │   │   ├── index.ts
│   │       │   │   │   └── types.ts
│   │       │   │   ├── components/
│   │       │   │   │   ├── OrderList/
│   │       │   │   │   ├── OrderDetail/
│   │       │   │   │   ├── OrderForm/
│   │       │   │   │   ├── OrderStatusBadge.vue
│   │       │   │   │   └── OrderTimeline.vue
│   │       │   │   ├── composables/
│   │       │   │   │   ├── useOrders.ts
│   │       │   │   │   ├── useOrder.ts
│   │       │   │   │   ├── useCreateOrder.ts
│   │       │   │   │   └── useCancelOrder.ts
│   │       │   │   ├── views/
│   │       │   │   │   ├── OrderListView.vue
│   │       │   │   │   ├── OrderDetailView.vue
│   │       │   │   │   └── OrderFormView.vue
│   │       │   │   └── index.ts
│   │       │   │
│   │       │   ├── dashboard/                 # 仪表盘模块
│   │       │   │   ├── api/
│   │       │   │   ├── components/
│   │       │   │   │   ├── StatCard.vue
│   │       │   │   │   ├── RevenueChart.vue
│   │       │   │   │   ├── RecentOrders.vue
│   │       │   │   │   └── UserGrowthChart.vue
│   │       │   │   ├── composables/
│   │       │   │   │   └── useDashboardStats.ts
│   │       │   │   ├── views/
│   │       │   │   │   └── DashboardView.vue
│   │       │   │   └── index.ts
│   │       │   │
│   │       │   ├── system/                    # 系统管理模块
│   │       │   │   ├── api/
│   │       │   │   ├── components/
│   │       │   │   │   ├── RoleForm.vue
│   │       │   │   │   ├── MenuTree.vue
│   │       │   │   │   ├── PermissionTree.vue
│   │       │   │   │   └── DictForm.vue
│   │       │   │   ├── composables/
│   │       │   │   ├── views/
│   │       │   │   │   ├── RoleView.vue
│   │       │   │   │   ├── MenuView.vue
│   │       │   │   │   └── DictView.vue
│   │       │   │   └── index.ts
│   │       │   │
│   │       │   └── notification/              # 通知模块
│   │       │       ├── api/
│   │       │       ├── components/
│   │       │       │   ├── NotificationBell.vue
│   │       │       │   ├── NotificationList.vue
│   │       │       │   └── NotificationItem.vue
│   │       │       ├── composables/
│   │       │       │   ├── useNotifications.ts
│   │       │       │   └── useWebSocket.ts
│   │       │       ├── stores/
│   │       │       │   └── notification.store.ts
│   │       │       └── index.ts
│   │       │
│   │       ├── components/                    # 应用级通用组件
│   │       │   ├── common/
│   │       │   │   ├── AppLoading.vue
│   │       │   │   ├── AppError.vue
│   │       │   │   ├── AppEmpty.vue
│   │       │   │   └── index.ts
│   │       │   ├── business/
│   │       │   │   ├── PageHeader/
│   │       │   │   │   ├── PageHeader.vue
│   │       │   │   │   └── index.ts
│   │       │   │   ├── DataTable/
│   │       │   │   │   ├── DataTable.vue
│   │       │   │   │   ├── DataTableColumn.vue
│   │       │   │   │   ├── DataTablePagination.vue
│   │       │   │   │   ├── DataTableFilter.vue
│   │       │   │   │   ├── DataTableToolbar.vue
│   │       │   │   │   └── index.ts
│   │       │   │   ├── SearchForm/
│   │       │   │   │   ├── SearchForm.vue
│   │       │   │   │   ├── SearchFormItem.vue
│   │       │   │   │   └── index.ts
│   │       │   │   ├── DetailCard/
│   │       │   │   ├── FileUpload/
│   │       │   │   ├── RichTextEditor/
│   │       │   │   ├── ImagePreview/
│   │       │   │   ├── ConfirmDialog/
│   │       │   │   ├── TreeSelect/
│   │       │   │   └── IconSelect/
│   │       │   └── index.ts
│   │       │
│   │       ├── composables/                   # 应用级通用组合式函数
│   │       │   ├── core/
│   │       │   │   ├── useRequest.ts          # 请求封装
│   │       │   │   ├── usePagination.ts       # 分页逻辑
│   │       │   │   ├── useTable.ts            # 表格逻辑
│   │       │   │   ├── useForm.ts             # 表单逻辑
│   │       │   │   ├── useDetail.ts           # 详情逻辑
│   │       │   │   └── useCrud.ts             # CRUD 组合
│   │       │   ├── ui/
│   │       │   │   ├── useLoading.ts
│   │       │   │   ├── useMessage.ts
│   │       │   │   ├── useDialog.ts
│   │       │   │   ├── useConfirm.ts
│   │       │   │   └── useTheme.ts
│   │       │   ├── utils/
│   │       │   │   ├── useDebounce.ts
│   │       │   │   ├── useThrottle.ts
│   │       │   │   ├── useLocalStorage.ts
│   │       │   │   ├── useClipboard.ts
│   │       │   │   ├── useEventListener.ts
│   │       │   │   └── useIntersectionObserver.ts
│   │       │   ├── business/
│   │       │   │   ├── usePermission.ts
│   │       │   │   ├── useDict.ts             # 字典数据
│   │       │   │   └── useExport.ts           # 导出功能
│   │       │   └── index.ts
│   │       │
│   │       ├── stores/                        # Pinia 状态管理
│   │       │   ├── index.ts
│   │       │   ├── modules/
│   │       │   │   ├── app.store.ts           # 应用状态
│   │       │   │   ├── user.store.ts          # 用户状态
│   │       │   │   ├── permission.store.ts    # 权限状态
│   │       │   │   ├── tab.store.ts           # 标签页状态
│   │       │   │   └── dict.store.ts          # 字典缓存
│   │       │   └── plugins/
│   │       │       └── persist.ts             # 持久化插件
│   │       │
│   │       ├── directives/                    # 自定义指令
│   │       │   ├── permission.ts              # v-permission
│   │       │   ├── loading.ts                 # v-loading
│   │       │   ├── debounce.ts                # v-debounce
│   │       │   ├── copy.ts                    # v-copy
│   │       │   ├── watermark.ts               # v-watermark
│   │       │   └── index.ts
│   │       │
│   │       ├── lib/                           # 第三方库封装
│   │       │   ├── axios/
│   │       │   │   ├── index.ts
│   │       │   │   ├── interceptors.ts
│   │       │   │   └── types.ts
│   │       │   ├── dayjs.ts
│   │       │   ├── echarts.ts
│   │       │   ├── i18n/
│   │       │   │   ├── index.ts
│   │       │   │   └── locales/
│   │       │   │       ├── zh-CN.json
│   │       │   │       └── en-US.json
│   │       │   └── sentry.ts
│   │       │
│   │       ├── styles/                        # 全局样式
│   │       │   ├── index.scss
│   │       │   ├── variables.scss
│   │       │   ├── mixins.scss
│   │       │   ├── reset.scss
│   │       │   ├── transition.scss
│   │       │   └── theme/
│   │       │       ├── light.scss
│   │       │       └── dark.scss
│   │       │
│   │       ├── assets/                        # 静态资源
│   │       │   ├── images/
│   │       │   ├── icons/
│   │       │   │   └── svg/
│   │       │   └── fonts/
│   │       │
│   │       └── types/                         # 类型定义
│   │           ├── global.d.ts
│   │           ├── env.d.ts
│   │           ├── router.d.ts
│   │           ├── components.d.ts            # 自动导入组件类型
│   │           └── auto-imports.d.ts          # 自动导入 API 类型
│   │
│   ├── admin/                                 # 管理后台应用
│   │   ├── package.json
│   │   ├── tsconfig.json
│   │   ├── vite.config.ts
│   │   └── src/
│   │       ├── main.ts
│   │       ├── App.vue
│   │       ├── modules/
│   │       │   ├── log/                       # 日志管理
│   │       │   │   ├── views/
│   │       │   │   │   ├── OperationLogView.vue
│   │       │   │   │   └── LoginLogView.vue
│   │       │   │   └── index.ts
│   │       │   ├── monitor/                   # 系统监控
│   │       │   │   ├── views/
│   │       │   │   │   ├── ServerMonitorView.vue
│   │       │   │   │   ├── CacheMonitorView.vue
│   │       │   │   │   └── OnlineUserView.vue
│   │       │   │   └── index.ts
│   │       │   └── config/                    # 系统配置
│   │       │       ├── views/
│   │       │       │   └── SystemConfigView.vue
│   │       │       └── index.ts
│   │       └── ...
│   │
│   └── mobile/                                # 移动端 H5
│       ├── package.json
│       ├── tsconfig.json
│       ├── vite.config.ts
│       └── src/
│           ├── main.ts
│           ├── App.vue
│           ├── modules/
│           │   ├── home/
│           │   ├── order/
│           │   └── profile/
│           ├── components/
│           ├── composables/
│           ├── styles/
│           │   └── mobile.scss               # 移动端适配样式
│           └── ...
│
├── tools/                                     # 工具脚本
│   ├── generators/                            # 代码生成器
│   │   ├── module/                            # 模块生成器
│   │   │   ├── index.ts
│   │   │   └── templates/
│   │   │       ├── api.hbs
│   │   │       ├── composable.hbs
│   │   │       ├── view.hbs
│   │   │       └── store.hbs
│   │   └── component/                         # 组件生成器
│   │       ├── index.ts
│   │       └── templates/
│   │           └── component.hbs
│   └── scripts/
│       ├── generate-api.ts                    # 生成 API 类型
│       ├── generate-icons.ts                  # 生成图标组件
│       └── analyze-bundle.ts
│
└── tests/                                     # E2E 测试
    ├── e2e/
    │   ├── auth.spec.ts
    │   ├── user.spec.ts
    │   └── order.spec.ts
    ├── fixtures/
    └── playwright.config.ts

Vue Module 内部结构详解

flowchart TB
    subgraph Vue Module
        API[api/] --> |类型定义| TYPES[types.ts]
        API --> |请求封装| COMPOSABLES[composables/]
        COMPOSABLES --> |数据提供| VIEWS[views/]
        COMPOSABLES --> |数据提供| COMPONENTS[components/]
        STORES[stores/] --> |全局状态| COMPOSABLES
        COMPONENTS --> |组合成| VIEWS
        VIEWS --> |注册到| ROUTES[routes]
    end

Composables 分层设计

flowchart LR
    subgraph 业务层
    A[useUsers] --> B[useCreateUser]
    A --> C[useUpdateUser]
    A --> D[useDeleteUser]
    end
    
    subgraph 通用层
    E[useCrud] --> A
    F[useTable] --> A
    G[usePagination] --> F
    end
    
    subgraph 基础层
    H[useRequest] --> E
    I[useLoading] --> H
    J[useMessage] --> H
    end

---

五、四框架结构对比总结

层次	Spring Boot	Gin	React	Vue
入口	project-boot/Application.java	cmd/server/main.go	apps/web/src/main.tsx	apps/web/src/main.ts
路由	@Controller + @RequestMapping	internal/server/router.go	app/router/routes.tsx	app/router/routes/
中间件/拦截器	filter/ + interceptor/	internal/middleware/	app/providers/	app/plugins/
业务模块	domain/{module}/	internal/service/{module}/	features/{module}/	modules/{module}/
请求处理	controller/	internal/handler/	features/*/api/	modules/*/api/
业务逻辑	service/	internal/service/	features/*/hooks/	modules/*/composables/
数据访问	repository/	internal/repository/	features/*/api/	modules/*/api/
数据模型	entity/ + dto/	internal/model/	features/*/types/	modules/*/types/
状态管理	无	无	stores/	stores/
通用组件	无	无	components/	components/
工具函数	util/	pkg/utils/	lib/ + hooks/	lib/ + composables/
配置	resources/application.yml	configs/	app/config/	app/config/
类型定义	DTO 类	struct	types/	types/
外部集成	integration/	internal/integration/	lib/	lib/
定时任务	job/	internal/job/	无	无
测试	test/	test/	tests/	tests/
部署配置	deploy/	deploy/	deploy/	deploy/

---

六、模块化设计原则

后端模块原则

flowchart TB
    subgraph 模块边界
    A[Controller] --> B[Service Interface]
    B --> C[Service Impl]
    C --> D[Repository Interface]
    D --> E[Repository Impl]
    end
    
    subgraph 跨模块通信
    F[Event] --> G[EventListener]
    H[Feign/gRPC] --> I[Remote Service]
    end
    
    C --> F
    C --> H

原则	说明
单一职责	一个模块只负责一个业务领域
接口隔离	通过接口暴露能力，隐藏实现
依赖倒置	依赖抽象而非具体实现
事件驱动	跨模块通过事件解耦
防腐层	外部系统通过 integration 层隔离

前端模块原则

flowchart TB
    subgraph Feature Module
    A[api] --> B[types]
    A --> C[hooks/composables]
    C --> D[components]
    D --> E[pages/views]
    F[stores] --> C
    end
    
    subgraph Shared
    G[ui components]
    H[common hooks]
    I[utils]
    end
    
    D --> G
    C --> H
    C --> I

原则	说明
功能内聚	相关代码放在同一模块目录
显式依赖	通过 index.ts 导出公开 API
状态下沉	状态尽量放在使用的地方
组件分层	UI 组件 → 业务组件 → 页面组件
类型先行	先定义类型，再实现逻辑

---