# EmbeddedDocStore

**Repository Path**: king_software/embedded-doc-store

## Basic Information

- **Project Name**: EmbeddedDocStore
- **Description**: 个轻量级嵌入式文档存储组件，基于本地文件系统保存 JSON 文档，支持：
● 基础文档 CRUD
● VersionedDocument 乐观锁（版本冲突检测）
● id.lock 文件写锁（跨进程/跨系统并发写入保护）
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-08
- **Last Updated**: 2026-05-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# EmbeddedDocStore

一个轻量级嵌入式文档存储组件，基于本地文件系统保存 JSON 文档，支持：

- 基础文档 CRUD
- `VersionedDocument` 乐观锁（版本冲突检测）
- `id.lock` 文件写锁（跨进程/跨系统并发写入保护）

## 1. 核心能力

- 通过 `collection + id` 定位文档
- 文档数据持久化到本地文件
- 每次写入自动维护 `version/createdAt/updatedAt`
- 支持 `expectedVersion` 条件写入，避免覆盖他人更新
- 写入前使用原子方式创建锁文件，降低多写入方并发冲突风险

## 2. 存储模型

文档文件：

```text
{root}/{collection}/{id}.json
```

写锁文件：

```text
{root}/{collection}/{id}.lock
```

`{id}.json` 内保存 `DocumentEnvelope`，包含：

- `id`
- `version`
- `createdAt`
- `updatedAt`
- `data`（业务对象序列化字节）

`{id}.lock` 内容是 JSON，字段固定为：

- `id`
- `createdAt`
- `expiresAt`

## 3. 写入流程说明（put）

`CollectionStore.put(...)` 在写文档前会先执行锁流程：

1. 原子创建 `id.lock`（`CREATE_NEW`）。
2. 如果锁已存在，读取 `expiresAt`：
1. 未过期：抛出 `LockConflictException`。
2. 已过期：删除旧锁并重试抢锁。
3. 拿到锁后执行版本检查和文档写入。
4. 写入完成后删除 `id.lock`。

当前锁默认过期时间：`30s`（`LOCK_TTL_MILLIS = 30000`）。

## 4. VersionedDocument 与版本冲突

`DocumentStore` 提供两种 `put`：

- `put(collection, id, value)`：不显式指定版本，按当前版本递增。
- `put(collection, id, value, expectedVersion)`：要求当前版本等于 `expectedVersion`，否则抛 `VersionConflictException`。

示例：

```java
DocumentStore store = DocumentStores.open(Path.of("./data"));

VersionedDocument<User> first = store.put("users", "u1", new User("Tom", 20));
VersionedDocument<User> second = store.put(
        "users",
        "u1",
        new User("Tom2", 21),
        first.getVersion()
);
```

## 5. 快速开始

环境要求：

- JDK 21
- Maven 3.9+

构建与测试：

```bash
mvn clean test
```

## 6. 目录结构

```text
src/main/java/com/lw/docstore/
├── api/
│   ├── DocumentStore.java
│   └── DocumentStores.java
├── core/
│   ├── FileDocumentStore.java
│   └── CollectionStore.java
├── model/
│   ├── DocumentEnvelope.java
│   ├── VersionedDocument.java
│   └── DocumentWriteLock.java
├── codec/
│   ├── Codec.java
│   └── JacksonCodec.java
└── exception/
    ├── DocumentStoreException.java
    ├── VersionConflictException.java
    └── LockConflictException.java
```

## 7. 测试说明

测试代码位于 `src/test/java/com/lw/`，新增/更新包括：

- `DocStoreVersionTest`：验证版本递增和版本冲突
- `DocStoreLockTest`：验证锁文件冲突、过期接管、写后删锁

## 8. 已知限制

- 锁依赖文件系统语义，在网络文件系统上行为取决于底层实现
- 锁过期时间当前为固定值（30s），未暴露外部配置入口
- 暂未提供查询、索引、分页等高级能力