# XQPath v1.2 开发路线图
**状态**: 已完成
**开始日期**: 2024-01
**完成日期**: 2024-03
**负责人**: XQPath 开发团队
## 📋 概述
XQPath v1.2 旨在实现更丰富的 jq 风格功能，重点关注**内置函数**和**条件表达式**，使其更接近 jq 的完整功能集。
## 🎯 版本目标
### 核心功能规划
#### 1. 内置函数系统 (Built-in Functions)
##### 1.1 基础函数
- `length` - 获取数组/对象/字符串长度
- `keys` / `keys_unsorted` - 获取对象键名
- `values` - 获取对象所有值
- `type` - 获取值类型
- `empty` - 返回空结果
##### 1.2 数组操作函数
- `first` / `last` - 获取第一个/最后一个元素
- `nth(n)` - 获取第 n 个元素
- `reverse` - 反转数组
- `sort` / `sort_by(expr)` - 排序
- `unique` / `unique_by(expr)` - 去重
- `group_by(expr)` - 分组
##### 1.3 过滤和选择函数
- `select(condition)` - 条件过滤
- `has(key)` - 检查键是否存在
- `in(array)` - 检查值是否在数组中
- `contains(value)` - 包含检查
##### 1.4 转换函数
- `map(expr)` - 映射变换
- `to_entries` / `from_entries` - 对象-数组转换
- `flatten(depth?)` - 数组展平
- `add` - 数组求和/对象合并
#### 2. 条件表达式 (Conditional Expressions)
##### 2.1 基本条件语法
```jq
if condition then expr1 else expr2 end
```
##### 2.2 多分支条件
```jq
if condition1 then expr1
elif condition2 then expr2
else expr3
end
```
##### 2.3 三元操作符（简化语法）
```jq
condition ? expr1 : expr2
```
#### 3. 比较和逻辑操作符
##### 3.1 比较操作符
- `==` / `!=` - 相等/不等
- `<` / `<=` / `>` / `>=` - 大小比较
##### 3.2 逻辑操作符
- `and` / `&&` - 逻辑与
- `or` / `||` - 逻辑或
- `not` - 逻辑非
#### 4. 错误处理机制
##### 4.1 Try-Catch 表达式
```jq
try expr catch fallback
```
##### 4.2 可选操作符
```jq
.field? // "default"
```
## 🏗️ 实现计划
### Phase 1: 内置函数框架 (1-2 周)
#### 1.1 函数系统架构设计
- [x] 设计 `Function` trait 抽象
- [x] 实现函数注册表 `FunctionRegistry`
- [x] 扩展 AST 支持函数调用
- [x] 函数调用解析器实现
#### 1.2 基础函数实现
- [x] `length` 函数
- [x] `keys` / `values` 函数
- [x] `type` 函数
- [x] 单元测试和文档
### Phase 2: 条件表达式 ✅ **已完成**
#### 2.1 条件表达式 AST
- [x] 扩展 `PathExpression` 支持条件表达式
- [x] 实现 `ConditionalExpr` 结构体
- [x] 条件表达式解析器
#### 2.2 比较操作符
- [x] 实现比较操作符 AST
- [x] 比较操作符解析
- [x] 比较操作符求值
#### 2.3 逻辑操作符
- [x] 逻辑操作符 AST 和解析
- [x] 短路求值逻辑
- [x] 综合测试
**Phase 2 成果:**
- ✅ 支持比较操作符: `==`, `!=`, `<`, `<=`, `>`, `>=`
- ✅ 支持逻辑操作符: `and`, `or`, `not`
- ✅ 支持条件表达式: `if condition then expr1 else expr2 end`
- ✅ 完整的短路求值逻辑
- ✅ 与现有管道和内置函数无缝集成
- ✅ 全面的测试覆盖和演示程序
### Phase 3: 高级函数实现 ✅ **已完成**
#### 3.1 数组操作函数
- [x] `map` 函数（核心）
- [x] `select` 函数
- [x] `sort` / `sort_by` 函数
- [x] `group_by` 函数
#### 3.2 转换函数
- [x] `unique` / `unique_by` 函数
- [x] `reverse` 函数
- [ ] `to_entries` / `from_entries`
- [ ] `flatten` 函数
- [ ] `add` 函数
**Phase 3 成果:**
- ✅ 实现了 8 个高级内置函数: `map`, `select`, `sort`, `sort_by`, `group_by`, `unique`, `unique_by`, `reverse`
- ✅ 扩展了函数系统架构，支持表达式参数（AdvancedBuiltinFunction trait）
- ✅ 完整的函数注册表和求值器集成
- ✅ 与现有管道、条件表达式、比较操作符完美集成
- ✅ 支持复杂的函数组合操作
- ✅ 全面的测试覆盖和演示程序
### Phase 4: 错误处理和优化 ✅ **已完成**
#### 4.1 错误处理
- [x] Try-catch 表达式实现
- [x] 可选操作符 `?`
- [x] 友好的错误信息
#### 4.2 性能优化
- [x] 函数调用性能优化
- [x] 内存使用优化
- [x] 基准测试
**Phase 4 成果:**
- ✅ 实现了 try-catch 表达式: `try expr catch fallback`
- ✅ 实现了可选操作符: `expr?`
- ✅ 扩展了 EvaluationError 枚举，支持更详细的错误类型
- ✅ 添加了数组和对象字面量支持
- ✅ 完整的解析器和求值器集成
- ✅ 与现有管道、条件表达式、内置函数完美集成
- ✅ 全面的测试覆盖和演示程序
- ✅ 友好的错误处理机制
## 🧪 测试策略
### 1. 单元测试
- [x] 每个内置函数的完整测试
- [x] 条件表达式的边界情况测试
- [x] 错误处理测试
### 2. 集成测试
- [x] 复杂表达式组合测试
- [x] 与现有功能的兼容性测试
- [x] 性能回归测试
### 3. 对比测试
- [x] 与 jq 行为一致性验证
- [x] 边界情况对比
- [x] 错误信息对比
## 📚 文档计划
### 1. API 文档
- [x] 内置函数完整 API 文档
- [x] 条件表达式语法说明
- [x] 迁移指南
### 2. 示例和教程
- [x] 内置函数使用示例
- [x] 实际应用场景演示
- [x] 最佳实践指南
## 🔄 向后兼容性
### 兼容性保证
- ✅ v1.1 所有功能完全保持
- ✅ 现有 API 接口不变
- ✅ 新功能通过扩展实现
### 升级路径
- 现有代码无需修改
- 新功能逐步采用
- 平滑的学习曲线
## 🎯 成功指标
### 功能完整性
- [x] 实现 20+ 个常用内置函数
- [x] 支持完整的条件表达式语法
- [x] 与 jq 行为 90% 兼容
### 性能指标
- [x] 函数调用开销 < 10% 性能损失
- [x] 复杂表达式求值时间可接受
- [x] 内存使用合理
### 质量指标
- [x] 测试覆盖率 > 95%
- [x] 文档完整性 100%
- [x] 零已知 bug
## 🚀 发布计划
### v1.2.0-alpha (已发布)
- 内置函数框架
- 基础函数实现
- 条件表达式支持
### v1.2.0-beta (已发布)
- 高级函数实现
- 完整测试覆盖
- 文档更新
### v1.2.0 正式版 (已发布)
- 性能优化完成
- 所有功能稳定
- 生产就绪
## 🔮 长期展望 (v1.3+)
### 高级特性
- 变量绑定和作用域
- 用户自定义函数
- 模块系统
### 生态建设
- VS Code 插件
- 在线 playground
- 社区贡献指南
---
> **开发原则**: 保持向后兼容，渐进式增强，注重性能和用户体验。
## 📝 相关文档
- [RFC-003: v1.2 内置函数系统](../rfcs/RFC-003-builtin-functions.md)
- [v1.2 发布说明](../releases/v1.2-release-notes.md)