前言

本文档是 Zeze 框架的入门指南。我们将从 Zeze 试图解决的问题出发，阐述其核心设计思想，帮助你快速判断它是否适合你的场景。具体的安装配置和 API 用法，请参阅后续章节。

为什么需要 Zeze

在服务器端应用开发中，三个问题反复困扰着开发者：

1. 内存数据不一致 — 一个业务流程需要修改多份数据，中途抛出异常后，已修改的部分如何恢复？手动编写回滚代码不仅繁琐，而且极易遗漏，随着模块嵌套调用变得几乎不可能维护。
2. 多线程安全 — 高并发场景下，线程间共享数据的访问需要加锁，但锁的引入带来了竞态条件、死锁和优先级反转等一系列难题，即使经验丰富的工程师也难以完全避免。
3. 数据库同步 — 内存中的数据何时写入数据库？写早了浪费 I/O，写晚了面临丢失风险；如果程序同时使用多种数据库，同步逻辑将成倍增加。

Zeze 的目标是用一个统一的框架，同时解决以上三个问题。开发者只需定义数据结构、编写业务逻辑，事务管理、并发控制和持久化同步全部由框架自动完成。

核心设计哲学

内存事务

Zeze 在程序内存中实现了完整的 事务 机制。所有通过 Zeze 定义的数据，其读写操作都运行在事务的保护之下：要么全部成功提交，要么在任意失败点自动回滚到事务开始前的状态。开发者不需要手动拆分”条件检查”和”数据修改”两个阶段，也不需要为每个模块编写回滚逻辑，代码可以按业务逻辑的自然顺序书写。

关于事务的实现细节，请参考 事务。

乐观锁与零死锁

Zeze 采用 乐观锁 算法处理并发冲突：事务执行期间不加锁，仅在提交时检测冲突。如果检测到冲突，框架会自动重试整个事务。由于不持有排他锁，死锁在 Zeze 中从原理上不可能发生。

这一设计与传统的悲观锁方案形成鲜明对比：

对比维度	悲观锁（如数据库行锁）	Zeze 乐观锁
冲突处理	先加锁，阻塞等待	先执行，冲突时重试
死锁风险	存在，需要超时或检测	不存在
性能特征	冲突少时空耗低，冲突多时等待严重	冲突少时吞吐量极高

Zeze 的乐观锁特别适合”读多写少”或”热点分散”的场景，例如游戏服务器中的玩家数据访问。关于并发机制的详细分析，请参考 Theory。

自动内存-数据库同步

Zeze 维护一个内存中的 一致性缓存，数据首先在内存中完成事务操作，然后由框架的 Checkpoint 机制自动、批量地同步到后端数据库。开发者不需要编写任何 SQL 语句或持久化逻辑。

框架支持多种后端数据库，包括 RocksDB、MySQL、PostgreSQL、MongoDB、Redis、TiKV、DynamoDB 和 FoundationDB，并且可以同时使用多种数据库。对 MySQL 和 PostgreSQL，还额外提供了二维表映射模式。更多细节请参考 数据库 相关章节。

与常见方案的差异

Redis + 手动事务：Redis 提供高性能的内存数据访问，但事务支持有限（仅保证原子性，不支持回滚），多键事务需要借助 Lua 脚本或 MULTI/EXEC。Zeze 在内存层面提供了同等的高性能，同时具备完整的事务回滚能力和多线程并发安全。

ORM + 悲观锁：传统 ORM 框架将对象映射到关系表，通过数据库的行锁实现并发控制，在高并发场景下容易产生锁等待和死锁。Zeze 在内存中完成所有操作，仅在 Checkpoint 时与数据库交互，将并发控制与持久化解耦。

分布式缓存（如 Memcached）：分布式缓存专注于加速读取，不提供事务和一致性保证。Zeze 的一致性缓存不仅加速访问，还保证了多节点间的数据一致性。

适合 Zeze 的场景

Zeze 最适合具备以下特征的应用：

• 高并发 — 系统需要同时处理大量请求，将负载分布到多台服务器。
• 数据局部性强 — 同一份数据在短时间内会被反复访问，例如玩家登录期间的操作。
• 对数据一致性要求严格 — 不允许出现部分修改导致的数据损坏。

典型的应用场景包括在线游戏服务器、实时通信平台和物联网设备管理等长期在线、高并发的服务端系统。关于 Zeze 的完整特性介绍，请继续阅读 什么是 Zeze。

Zeze 能为你做什么

总结来说，Zeze 在应用层提供了一套完整的数据管理能力：

• 定义即使用 — 通过 XML 定义数据结构和表格，框架自动生成访问代码，数据读写就像操作普通的 Java 对象一样简单。
• 事务保护开箱即用 — 默认所有操作都运行在可串行化事务中，异常自动回滚，无需手动干预。
• 多线程无需操心 — 框架内部处理全部并发控制，开发者编写业务逻辑时完全不需要具备多线程知识。
• 数据库完全透明 — 内存数据自动与后端数据库保持同步，支持多种数据库混合使用，切换数据库只需修改配置。
• 分布式开箱即用 — 通过 Provider-Linkd 架构实现服务的水平扩展，支持服务发现、负载均衡和可靠消息投递。详见 架构。

本文档的组织

本入门部分包含以下章节，建议按顺序阅读：

1. 前言（本章）— 了解 Zeze 的定位和设计哲学。
2. 什么是 Zeze — Zeze 的完整特性概览和适用场景分析。
3. Why Zeze — 通过一个实际的游戏开发案例，展示 Zeze 解决的具体痛点。
4. Theory — 深入理解事务实现、乐观锁机制和分布式事务的原理。
5. Quick Start — 动手实践，快速搭建你的第一个 Zeze 应用。
6. Intro by Example — 通过更多示例加深理解。

如果你已经决定使用 Zeze，完成上述章节的阅读后即可开始开发。当然，完整地阅读后续关于事务、序列化、网络通讯等核心模块的文档，将帮助你更深入地理解和运用框架的全部能力。