FastBSON

🚀 项目概述

核心特性

性能优势

快速开始

依赖配置

<dependency>
 <groupId>com.cloud</groupId>
 <artifactId>fastbson</artifactId>
 <version>1.0.0-SNAPSHOT</version>
</dependency>

基本使用

// 1. 创建解析器,指定需要的字段
FastBsonParser parser = FastBsonParser.builder()
 .fields("name", "age", "email")
 .build();
// 2. 解析 BSON 数据
byte[] bsonData = ...;
Map<String, Object> result = parser.parse(bsonData);
// 3. 获取字段值
String name = (String) result.get("name");
Integer age = (Integer) result.get("age");
String email = (String) result.get("email");

类型安全访问

// 使用类型安全的访问器
FastBsonParser parser = FastBsonParser.builder()
 .fields("age", "salary", "active")
 .build();
BsonDocument doc = parser.parseToDocument(bsonData);
int age = doc.getInt("age");
double salary = doc.getDouble("salary");
boolean active = doc.getBoolean("active");
// 支持默认值
String department = doc.getString("department", "Unknown");

使用示例

场景 1: 完整文档解析 - HashMap 模式

import com.cloud.fastbson.FastBson;
import com.cloud.fastbson.document.BsonDocument;
import com.cloud.fastbson.document.hashmap.HashMapBsonDocumentFactory;
import com.cloud.fastbson.reader.BsonReader;
// 设置为 HashMap 模式(默认,完整解析)
FastBson.setDocumentFactory(HashMapBsonDocumentFactory.INSTANCE);
// 解析 BSON 数据
byte[] bsonData = ...; // 来自 MongoDB 或其他来源
BsonDocument doc = FastBson.parse(new BsonReader(bsonData));
// 访问字段(已全部解析,速度快)
String name = doc.getString("name");
int age = doc.getInt32("age");
double salary = doc.getDouble("salary");
boolean active = doc.getBoolean("active");
// 性能:2-3x vs MongoDB BSON(中等文档)
// 内存:完整解析,内存占用较高

场景 2: 部分字段提取 - PartialParser 早退模式

import com.cloud.fastbson.parser.PartialParser;
import java.util.Map;
// 创建 PartialParser,指定需要的字段
PartialParser parser = new PartialParser("userId", "timestamp", "eventType");
// 启用早退优化(找到目标字段后立即停止解析)
parser.setEarlyExit(true);
// 解析 BSON 数据(只解析需要的字段)
byte[] bsonData = ...; // 100+ 字段的大文档
Map<String, Object> result = parser.parse(bsonData);
// 获取字段值
String userId = (String) result.get("userId");
Long timestamp = (Long) result.get("timestamp");
String eventType = (String) result.get("eventType");
// 性能:7-8x vs MongoDB BSON(大文档,少量字段)
// 适合:日志解析、事件流处理、数据管道

场景 3: 零复制惰性解析 - IndexedBsonDocument 模式

import com.cloud.fastbson.FastBson;
import com.cloud.fastbson.document.BsonDocument;
import com.cloud.fastbson.document.indexed.IndexedBsonDocumentFactory;
import com.cloud.fastbson.reader.BsonReader;
// 设置为 Indexed 模式(零复制,惰性解析)
FastBson.setDocumentFactory(IndexedBsonDocumentFactory.INSTANCE);
// 解析 BSON 数据(仅构建字段索引,不解析值)
byte[] bsonData = ...; // 100+ 字段的大文档
BsonDocument doc = FastBson.parse(new BsonReader(bsonData));
// 按需访问字段(惰性解析,只解析访问的字段)
String field0 = doc.getString("field0"); // 首次访问,解析并缓存
int field5 = doc.getInt32("field5"); // 首次访问,解析并缓存
String field0Again = doc.getString("field0"); // 二次访问,直接从缓存读取
// 性能:3-5x vs MongoDB BSON(重复访问)
// 内存:70% 降低(~30 bytes/field vs ~200 bytes/field)
// 适合:内存敏感场景、需要多次访问同一文档

场景 4: 嵌套文档和数组访问

import com.cloud.fastbson.FastBson;
import com.cloud.fastbson.document.BsonDocument;
import com.cloud.fastbson.document.BsonArray;
import com.cloud.fastbson.reader.BsonReader;
// 解析包含嵌套结构的 BSON 文档
byte[] bsonData = ...; // { "user": { "name": "Alice", "tags": ["admin", "developer"] } }
BsonDocument doc = FastBson.parse(new BsonReader(bsonData));
// 访问嵌套文档
BsonDocument user = doc.getDocument("user");
String userName = user.getString("name");
// 访问嵌套数组
BsonArray tags = user.getArray("tags");
String firstTag = tags.getString(0);
String secondTag = tags.getString(1);
// 遍历数组
for (int i = 0; i < tags.size(); i++) {
 String tag = tags.getString(i);
 System.out.println("Tag: " + tag);
}
// 深度嵌套访问(支持 50+ 层嵌套)
BsonDocument level1 = doc.getDocument("level1");
BsonDocument level2 = level1.getDocument("level2");
int deepValue = level2.getInt32("value");

场景 5: 性能敏感场景 - 日志解析

import com.cloud.fastbson.parser.PartialParser;
import java.util.Map;
import java.util.concurrent.ArrayBlockingQueue;
// 日志解析器(只提取关键字段)
public class LogParser {
 private final PartialParser parser;
 public LogParser() {
 // 只提取日志的关键字段
 this.parser = new PartialParser(
 "timestamp", "level", "message", "userId", "traceId"
 );
 this.parser.setEarlyExit(true); // 早退优化
 }
 public LogEntry parse(byte[] bsonLog) {
 Map<String, Object> result = parser.parse(bsonLog);
 return new LogEntry(
 (Long) result.get("timestamp"),
 (String) result.get("level"),
 (String) result.get("message"),
 (String) result.get("userId"),
 (String) result.get("traceId")
 );
 }
}
// 使用示例
LogParser logParser = new LogParser();
ArrayBlockingQueue<byte[]> logQueue = new ArrayBlockingQueue<>(10000);
// 高吞吐量处理(7-8x vs MongoDB BSON)
while (true) {
 byte[] bsonLog = logQueue.take();
 LogEntry entry = logParser.parse(bsonLog);
 processLog(entry);
}

场景 6: 内存敏感场景 - 大量文档缓存

import com.cloud.fastbson.FastBson;
import com.cloud.fastbson.document.BsonDocument;
import com.cloud.fastbson.document.indexed.IndexedBsonDocumentFactory;
import com.cloud.fastbson.reader.BsonReader;
import java.util.HashMap;
import java.util.Map;
// 设置为 Indexed 模式(内存占用降低 70%)
FastBson.setDocumentFactory(IndexedBsonDocumentFactory.INSTANCE);
// 文档缓存(零复制,惰性解析)
public class DocumentCache {
 private final Map<String, BsonDocument> cache = new HashMap<>();
 public void cache(String id, byte[] bsonData) {
 // 只构建索引,不解析值(内存占用低)
 BsonDocument doc = FastBson.parse(new BsonReader(bsonData));
 cache.put(id, doc);
 }
 public String getUserName(String id) {
 BsonDocument doc = cache.get(id);
 // 按需解析字段(惰性解析)
 return doc.getString("name");
 }
}
// 使用示例
DocumentCache cache = new DocumentCache();
// 缓存 10,000 个文档(内存占用降低 70%)
for (int i = 0; i < 10000; i++) {
 byte[] bsonData = fetchFromDatabase(i);
 cache.cache("doc_" + i, bsonData);
}
// 按需访问(惰性解析,只解析访问的字段)
String name = cache.getUserName("doc_1234");

场景 7: 跨库兼容性 - 与 org.mongodb:bson 互操作

import com.cloud.fastbson.FastBson;
import com.cloud.fastbson.document.BsonDocument;
import com.cloud.fastbson.reader.BsonReader;
import org.bson.BsonBinaryWriter;
import org.bson.io.BasicOutputBuffer;
// 1. 使用 org.mongodb:bson 生成 BSON 数据
BasicOutputBuffer buffer = new BasicOutputBuffer();
BsonBinaryWriter writer = new BsonBinaryWriter(buffer);
writer.writeStartDocument();
writer.writeString("name", "Alice");
writer.writeInt32("age", 30);
writer.writeBoolean("active", true);
writer.writeEndDocument();
writer.flush();
byte[] bsonData = buffer.toByteArray();
// 2. 使用 FastBSON 解析(完全兼容)
BsonDocument doc = FastBson.parse(new BsonReader(bsonData));
// 3. 访问字段
String name = doc.getString("name");
int age = doc.getInt32("age");
boolean active = doc.getBoolean("active");
System.out.println("Name: " + name + ", Age: " + age + ", Active: " + active);
// 输出: Name: Alice, Age: 30, Active: true
// FastBSON 完全兼容 BSON spec v1.1,支持所有 MongoDB 生成的 BSON 数据

场景 8: 多线程场景 - 线程安全和对象池

import com.cloud.fastbson.parser.PartialParser;
import java.util.Map;
import java.util.concurrent.ExecutorService;
import java.util.concurrent.Executors;
// 多线程解析器(PartialParser 是线程安全的)
public class MultiThreadedParser {
 private final PartialParser parser;
 private final ExecutorService executor;
 public MultiThreadedParser() {
 // 创建解析器(线程安全,可共享)
 this.parser = new PartialParser("field1", "field2", "field3");
 this.parser.setEarlyExit(true);
 // 创建线程池
 this.executor = Executors.newFixedThreadPool(8);
 }
 public void parseAsync(byte[] bsonData) {
 executor.submit(() -> {
 // 每个线程安全地使用共享的 parser
 Map<String, Object> result = parser.parse(bsonData);
 processResult(result);
 });
 }
 private void processResult(Map<String, Object> result) {
 // 处理解析结果
 System.out.println("Parsed: " + result);
 }
}
// 使用示例
MultiThreadedParser parser = new MultiThreadedParser();
// 并发解析(线程安全,无竞争)
for (int i = 0; i < 10000; i++) {
 byte[] bsonData = generateBsonData(i);
 parser.parseAsync(bsonData);
}

场景 9: 实际业务场景 - 用户行为数据聚合

import com.cloud.fastbson.parser.PartialParser;
import java.util.Map;
import java.util.HashMap;
import java.util.concurrent.atomic.AtomicLong;
// 用户行为数据聚合器
public class UserBehaviorAggregator {
 private final PartialParser parser;
 private final Map<String, AtomicLong> eventCounts = new HashMap<>();
 public UserBehaviorAggregator() {
 // 只提取分析需要的字段(从 100+ 字段中提取 4 个)
 this.parser = new PartialParser(
 "userId", "eventType", "timestamp", "duration"
 );
 this.parser.setEarlyExit(true); // 早退优化(7-8x speedup)
 }
 public void aggregate(byte[] bsonEvent) {
 // 快速解析(只解析需要的 4 个字段)
 Map<String, Object> event = parser.parse(bsonEvent);
 String eventType = (String) event.get("eventType");
 Long duration = (Long) event.get("duration");
 // 统计事件次数
 eventCounts.computeIfAbsent(eventType, k -> new AtomicLong())
 .incrementAndGet();
 // 处理业务逻辑
 if (duration > 10000) {
 // 慢事件告警
 alertSlowEvent(event);
 }
 }
 public void printStatistics() {
 System.out.println("=== 用户行为统计 ===");
 eventCounts.forEach((eventType, count) -> {
 System.out.println(eventType + ": " + count.get());
 });
 }
 private void alertSlowEvent(Map<String, Object> event) {
 System.out.println("ALERT: Slow event detected - " + event);
 }
}
// 使用示例
UserBehaviorAggregator aggregator = new UserBehaviorAggregator();
// 处理 1,000,000 个事件(7-8x vs MongoDB BSON)
for (int i = 0; i < 1000000; i++) {
 byte[] bsonEvent = fetchEventFromQueue();
 aggregator.aggregate(bsonEvent);
}
aggregator.printStatistics();

场景选择指南

默认值和异常处理

import com.cloud.fastbson.FastBson;
import com.cloud.fastbson.document.BsonDocument;
import com.cloud.fastbson.reader.BsonReader;
BsonDocument doc = FastBson.parse(new BsonReader(bsonData));
// 使用默认值(字段不存在或类型不匹配时返回默认值)
String name = doc.getString("name", "Unknown");
int age = doc.getInt32("age", 0);
double salary = doc.getDouble("salary", 0.0);
boolean active = doc.getBoolean("active", false);
// 检查字段是否存在
if (doc.contains("email")) {
 String email = doc.getString("email");
 System.out.println("Email: " + email);
}
// 检查字段是否为 null
if (doc.isNull("deletedAt")) {
 System.out.println("Document is not deleted");
}
// 获取字段类型
byte fieldType = doc.getType("age");
if (fieldType == BsonType.INT32) {
 int age = doc.getInt32("age");
}

项目状态

✅ Phase 1 完成 (基础框架) - 100%

✅ Phase 2 完成 (零复制惰性解析与早退优化) - 100%

⏳ 下一步:Phase 3 (性能优化)

架构设计

核心组件

FastBSON
├── BsonReader # 底层字节流读取器
├── TypeHandler # 类型解析处理器
├── FieldMatcher # 字段匹配器(待实现)
├── ValueSkipper # 值跳过器(待实现)
└── PartialParser # 部分字段解析器(待实现)

支持的 BSON 类型

开发规范

技术栈

开发要求

性能差异分析

为什么 FastBSON 比 MongoDB BSON 快 3.88 倍?

1. 零拷贝设计 - 减少内存分配

// 直接操作原始字节数组,零拷贝
BsonReader reader = new BsonReader(bsonData); // 只保存引用
int value = reader.readInt32(); // 直接从数组读取

// 需要 ByteBuffer 包装层
ByteBuffer buffer = ByteBuffer.wrap(bsonData); // 创建包装对象
BsonBinaryReader reader = new BsonBinaryReader(
 new ByteBufferBsonInput(new ByteBufNIO(buffer)) // 多层包装
);

2. 简化的类型处理 - 单一处理器

// 单一 TypeHandler,switch-case 直接分派
TypeHandler handler = new TypeHandler();
Object value = handler.parseValue(reader, type); // 一次方法调用

// 复杂的 Codec 架构,多层间接调用
BsonDocumentCodec codec = new BsonDocumentCodec();
BsonDocument doc = codec.decode(reader, context); // Codec 层次结构

3. 高效的字节序转换 - 位运算优化

// 直接使用位运算,内联友好
public int readInt32() {
 return (data[pos++] & 0xFF)
 | ((data[pos++] & 0xFF) << 8)
 | ((data[pos++] & 0xFF) << 16)
 | ((data[pos++] & 0xFF) << 24);
}

// ByteBuffer 间接调用,难以内联
buffer.order(ByteOrder.LITTLE_ENDIAN);
int value = buffer.getInt(); // 虚方法调用

4. 轻量级状态管理 - 最小化上下文

public class BsonReader {
 private byte[] data; // 数据引用
 private int position; // 唯一状态
 // 仅维护 2 个字段
}

// BsonBinaryReader 维护复杂上下文
// - 多层 Input 抽象
// - 状态机管理
// - 上下文栈
// - 验证器等

5. 对象创建优化 - 直接返回基本类型包装

// 返回已缓存的 Integer 对象(-128~127)
return reader.readInt32(); // 自动装箱使用缓存

// 创建 BsonInt32 包装对象
return new BsonInt32(value); // 每次都创建新对象

性能对比总结

性能优化技术

已实现

待实现(Phase 3)

构建和测试

编译

mvn clean compile

运行测试

mvn test

代码覆盖率

mvn test jacoco:report
# 查看报告: target/site/jacoco/index.html

性能测试

mvn test -Dtest=FastBsonBenchmark

文档

贡献指南

Commit 规范

feat: 新功能
fix: Bug 修复
perf: 性能优化
test: 测试
docs: 文档
refactor: 重构
chore: 构建/工具

许可证

致谢

联系方式

Phase 2 性能基线测试(v1.0.0-SNAPSHOT)

✅ Phase 2 完成 - 零复制惰性解析与早退优化

📊 Phase 1: HashMap 全文档解析(基线)

场景: 50字段文档,完整解析
FastBSON (HashMap): 113ms
MongoDB BSON: 381ms
性能提升: 3.35x ✅ (目标: 3.88x)

📊 Phase 2.A: PartialParser (早退优化)

场景: 100字段文档,提取5个字段 (5/100)
FastBSON (PartialParser): 51-71ms
MongoDB BSON (完整解析): 412-552ms
性能提升: 7.67-7.96x ✅ (目标: 10-20x,接近目标)

📊 Phase 2.B: IndexedBsonDocument (零复制惰性解析)

场景: 100字段文档,构建索引 + 访问5个字段
FastBSON (IndexedDocument): 163-212ms
MongoDB BSON (完整解析): 552-658ms
性能提升: 3.10-3.38x ✅
优势: 零复制架构,内存占用降低 70%

🔍 综合对比表格

┌─────────────────────────────┬──────────────┬────────────┬──────────────┐
│ 实现方式 │ 耗时 (ms) │ vs MongoDB │ 特点 │
├─────────────────────────────┼──────────────┼────────────┼──────────────┤
│ Phase 2.A: PartialParser │ 71 │ 7.67x │ 早退优化 │
│ Phase 2.B: IndexedDocument │ 163 │ 3.38x │ 零复制惰性 │
│ MongoDB BSON (baseline) │ 552 │ 1.00x │ 完整解析 │
└─────────────────────────────┴──────────────┴────────────┴──────────────┘

📌 使用建议

Phase 2.A: PartialParser (早退优化)

// 适用场景:一次性部分字段提取
PartialParser parser = new PartialParser("field0", "field1", "field2");
parser.setEarlyExit(true);
Map<String, Object> result = parser.parse(bsonData);

Phase 2.B: IndexedBsonDocument (零复制惰性解析)

// 适用场景:需要重复访问或内存敏感
FastBson.useIndexedFactory();
BsonDocument doc = DocumentParser.INSTANCE.parse(new BsonReader(bsonData));
int value = doc.getInt32("field0");

🎯 Phase 2 成果总结

🚀 性能基线测试用法

运行完整性能基线测试(推荐)

# 一次运行,展示所有场景的性能对比
mvn test -Dtest=PerformanceBenchmark#testCompletePerformanceBaseline

====================================================================================================
 FastBSON 性能基线测试报告
====================================================================================================
┌──────────────────────────────┬──────────────────────┬──────────┬──────────┬────────────┐
│ 场景 │ 实现方式 │ FastBSON │ MongoDB │ 性能提升 │
├──────────────────────────────┼──────────────────────┼──────────┼──────────┼────────────┤
│ Phase 1: 50字段完整解析 │ HashMap (eager) │ 93 ms │ 204 ms │ 2.18x │
│ Phase 2.A: 100字段部分解析(5/100) │ PartialParser (early-exit) │ 51 ms │ 410 ms │ 7.99x │
│ Phase 2.B: 100字段零复制惰性(5/100) │ IndexedDocument (zero-copy) │ 74 ms │ 422 ms │ 5.64x │
└──────────────────────────────┴──────────────────────┴──────────┴──────────┴────────────┘

运行单个场景测试

# Phase 1: HashMap 完整解析模式
mvn test -Dtest=PerformanceBenchmark#testPhase1_HashMap_50Fields
# Phase 2.A: PartialParser 早退优化模式
mvn test -Dtest=PerformanceBenchmark#testPhase2A_PartialParser_5of100
# Phase 2.B: IndexedBsonDocument 零复制惰性解析模式
mvn test -Dtest=PerformanceBenchmark#testPhase2B_IndexedDocument_5of100

测试类说明

自定义Benchmark场景

import com.cloud.fastbson.benchmark.*;
public class MyBenchmark {
 @Test
 public void testMyScenario() {
 // 1. 生成测试数据
 byte[] bsonData = BsonTestDataGenerator.generateDocument(100);
 // 2. 运行你的实现
 long start = System.nanoTime();
 // ... your implementation ...
 long time = System.nanoTime() - start;
 // 3. 创建结果
 BenchmarkResult result = BenchmarkResult.builder()
 .scenarioName("My Custom Scenario")
 .fastbsonMode("Custom Mode")
 .fastbsonTimeNanos(time)
 .mongoTimeNanos(mongoTime)
 .speedup((double) mongoTime / time)
 .description("场景描述")
 .target("目标性能")
 .build();
 // 4. 生成报告
 String report = BenchmarkReport.generate(List.of(result));
 System.out.println(report);
 }
}