13 KiB

Raw Blame History

Issue #025: 预留导入管理机制

工单编号: #025
工单标题: 实现统一的预留导入管理机制
优先级: 中
类型: 技术基础设施
创建日期: 2026-02-19
预计工期: 2-3周
状态: 待处理

📋 问题背景

当前痛点

在NAC项目开发过程中，经常遇到以下问题：

未使用导入警告泛滥
- 开发者为未来功能预留导入，但编译器报告unused import警告
- 为了消除警告，开发者可能：
  - 使用#[allow(unused_imports)]掩盖问题（危险！）
  - 删除导入，导致未来开发者不知道原计划（埋雷！）
  - 保留警告，干扰正常开发（烦人！）
技术债缺乏可见性
- 预留的功能和依赖没有统一记录
- 后续开发者不知道为什么某些代码被注释掉
- 无法追踪预留项的生命周期
多编译器不一致
- Rust、Charter、CNNL三套编译器处理方式不同
- 缺乏统一的预留导入规范
- 团队协作困难

触发事件

在Issue #024 (nac-ai-valuation)开发过程中，遇到了大量未使用导入警告。经过讨论，确定了以下原则：

❌ 不使用#[allow(unused)]掩盖问题
❌ 不随意删除可能需要的导入
✅ 需要一个正式的预留导入管理机制

🎯 解决方案

核心理念

将"未使用的导入"从"代码异味"转变为"未来路线图的活文档"

通过统一的预留属性语法，让预留导入成为：

📝 可文档化 - 每个预留都有编号和说明
🔍 可追踪 - 可以生成预留清单，纳入技术债管理
🔄 可审计 - 可以检查预留是否过期，是否应该清理
🤝 可协作 - 团队成员清楚知道预留的目的和计划

设计原则

统一性 - Rust、Charter、CNNL使用相同的语法和语义
明确性 - 每个预留都有唯一编号和清晰说明
可进化 - 支持预留的启用、延期、废弃
可审计 - 可以生成报告，追踪预留生命周期
零成本 - 不影响编译性能和运行时性能

📐 技术方案

1. 统一预留属性语法

1.1 Rust（通过自定义属性）

#[reserved(
    id = "XIC-001",
    description = "跨链桥升级所需，预计2026Q3启用",
    owner = "bridge-team",
    deadline = "2026-09-30"
)]
use some_crate::FutureModule;

1.2 Charter（语言原生支持）

@reserved(
    id="XIC-002",
    description="XTZH v2 预言机接口",
    owner="oracle-team",
    deadline="2027-03-31"
)
import future::oracle_v2;

1.3 CNNL（宪法层预留条款）

// 宪法条款也可有预留导入
@reserved(
    id="CON-001",
    description="国际商事法律规则库",
    owner="legal-team",
    deadline="2027-12-31"
)
import law::cisg;

2. 预留编号规范

2.1 编号格式

<项目代号>-<序号>

2.2 项目代号

CORE - 核心模块
XIC - 跨链互操作
BRIDGE - 跨链桥
ORACLE - 预言机
AIVAL - AI估值
CON - 宪法层
RPC - RPC接口
TOOL - 工具链

2.3 序号规则

从001开始连续编号
同一项目代号下序号唯一
废弃的编号不重用

3. 预留属性字段

3.1 必填字段

id - 预留编号（全局唯一）
description - 预留说明（简短描述用途）

3.2 可选字段

owner - 负责团队或负责人
deadline - 预计启用时间（YYYY-MM-DD）
issue - 关联的Issue编号
status - 状态（planned/in-progress/blocked/cancelled）
priority - 优先级（high/medium/low）

4. 编译器行为

4.1 Rust编译器扩展

通过cargo-constitution Lint实现
识别#[reserved]属性
不报告unused import警告
生成预留清单文件reserved_deps.json

4.2 Charter编译器

原生支持@reserved属性
编译时验证预留编号唯一性
支持--list-reserved选项输出清单

4.3 CNNL编译器

原生支持@reserved属性
与宪法治理流程集成
预留的启用可能需要治理投票

5. 工具链支持

5.1 cargo-constitution

# 查看所有预留
cargo reserved list

# 查看特定项目的预留
cargo reserved list --project XIC

# 检查过期预留
cargo reserved check-expired

# 生成预留报告
cargo reserved report --format markdown

# 启用预留（移除@reserved属性）
cargo reserved activate XIC-001

# 废弃预留（添加cancelled状态）
cargo reserved cancel XIC-002 --reason "需求变更"

5.2 IDE插件

高亮显示预留导入
鼠标悬停显示预留信息
快速跳转到相关Issue
提示即将过期的预留

5.3 CI集成

# .github/workflows/check-reserved.yml
name: Check Reserved Imports

on: [push, pull_request]

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Check expired reserved imports
        run: cargo reserved check-expired --fail-if-expired
      - name: Generate reserved report
        run: cargo reserved report --format markdown > reserved_report.md
      - name: Upload report
        uses: actions/upload-artifact@v2
        with:
          name: reserved-report
          path: reserved_report.md

6. 预留生命周期管理

6.1 预留状态

planned - 已规划，等待实现
in-progress - 正在实现中
blocked - 被阻塞，无法继续
cancelled - 已取消，不再需要
activated - 已启用，移除预留标记

6.2 生命周期流程

planned → in-progress → activated
   ↓           ↓
cancelled   blocked → in-progress

6.3 过期检查

如果预留超过deadline未启用，CI发出警告
如果预留超过1年未启用，建议评估是否取消
定期（每季度）审查所有预留项

📦 交付物

1. 技术规范文档

预留导入管理机制规范（本文档）
附件G：多编译器协同使用细则（更新版）
预留编号分配指南
预留生命周期管理流程

2. Rust工具链

cargo-constitution Lint扩展
预留属性宏实现
cargo reserved子命令
预留清单生成器

3. Charter编译器

@reserved属性解析
预留编号唯一性检查
--list-reserved选项
预留清单输出

4. CNNL编译器

@reserved属性解析
与治理流程集成
预留条款管理

5. IDE插件

VSCode插件（Rust）
Charter语言服务器扩展
CNNL语言服务器扩展

6. CI/CD集成

GitHub Actions工作流
GitLab CI配置
预留报告生成脚本

7. 文档和示例

使用指南
最佳实践
示例项目
FAQ

🎯 验收标准

1. 功能完整性

三种语言（Rust/Charter/CNNL）都支持预留属性
编译器能正确识别和处理预留导入
不报告预留导入的unused警告
能生成预留清单

2. 工具链完整性

cargo reserved命令可用
IDE插件正常工作
CI集成正常运行
预留报告格式正确

3. 文档完整性

技术规范文档完整
使用指南清晰
示例代码可运行
FAQ覆盖常见问题

4. 质量标准

零编译警告
所有测试通过
代码覆盖率>80%
性能无明显下降

📅 实施计划

Phase 1: 规范制定（3天）

完善技术规范文档
制定预留编号分配规则
设计预留清单格式
评审和确认

Phase 2: Rust工具链（1周）

实现cargo-constitution Lint扩展
实现预留属性宏
实现cargo reserved子命令
编写测试

Phase 3: Charter编译器（3天）

实现@reserved属性解析
实现预留编号检查
实现--list-reserved选项
编写测试

Phase 4: CNNL编译器（3天）

实现@reserved属性解析
集成治理流程
编写测试

Phase 5: IDE插件（3天）

实现VSCode插件
实现语言服务器扩展
测试和优化

Phase 6: CI/CD集成（2天）

编写GitHub Actions工作流
编写预留报告生成脚本
测试CI集成

Phase 7: 文档和示例（2天）

编写使用指南
编写最佳实践
创建示例项目
编写FAQ

Phase 8: 测试和优化（2天）

集成测试
性能测试
用户测试
优化和修复

🔗 依赖关系

上游依赖

NAC编译器工具链（Charter/CNNL）
cargo-constitution基础框架
NAC治理流程

下游影响

所有NAC模块开发
代码审查流程
技术债管理
项目规划

📊 成功指标

量化指标

预留导入使用率 > 80%（团队采纳度）
unused import警告减少 > 90%
技术债可见性提升 100%（所有预留都有记录）
预留启用率 > 60%（预留最终被使用的比例）

质量指标

团队满意度 > 4/5
文档完整性 100%
工具稳定性 > 99%
性能影响 < 1%

⚠️ 风险和挑战

技术风险

编译器集成复杂度
- 风险：三套编译器集成工作量大
- 缓解：分阶段实施，先Rust后Charter/CNNL
性能影响
- 风险：预留检查可能影响编译速度
- 缓解：优化算法，使用缓存
向后兼容性
- 风险：现有代码需要迁移
- 缓解：提供迁移工具，保持兼容期

流程风险

团队采纳度
- 风险：团队可能不愿意使用新机制
- 缓解：提供培训，展示价值，强制在新代码中使用
维护成本
- 风险：预留项过多导致维护困难
- 缓解：定期审查，自动化过期检查

💡 最佳实践

1. 何时使用预留导入

✅ 应该使用：

已确定的未来功能，但当前不实现
跨模块依赖，等待上游模块完成
实验性功能，需要feature flag控制
技术债，计划未来重构

❌ 不应该使用：

不确定是否需要的功能
可以立即实现的功能
已废弃的功能
临时测试代码

2. 预留说明编写规范

// ✅ 好的预留说明
#[reserved(
    id = "XIC-001",
    description = "跨链桥升级到IBC协议，等待ibc-rs v2.0稳定版发布",
    owner = "bridge-team",
    deadline = "2026-09-30",
    issue = "#123"
)]
use ibc_rs::v2::Context;

// ❌ 不好的预留说明
#[reserved(id = "XIC-002", description = "可能需要")]
use some_crate::Something;

3. 预留生命周期管理

每月检查即将过期的预留
每季度审查所有预留项
及时更新预留状态
启用后立即移除预留标记

📚 参考资料

外部参考

Rust RFC: Custom attributes
Cargo book: Custom commands
Language Server Protocol

🎓 经验教训（来自Issue #024）

1. 不要使用`#[allow(unused)]`掩盖问题

未使用的代码可能是逻辑错误或安全隐患，不应该用属性掩盖。

2. 不要随意删除导入

测试代码可能需要，应该在测试模块中导入，不要给未来开发者埋雷。

3. 所有字段都应该有用途

如果不用就删除，如果用就实际使用，不要保留无用字段。

4. 需要正式的预留机制

临时的注释和TODO不够，需要正式的、可追踪的预留机制。

✅ 验收清单

技术实现

Rust工具链完成
Charter编译器完成
CNNL编译器完成
IDE插件完成
CI/CD集成完成

文档完善

技术规范完成
使用指南完成
最佳实践完成
FAQ完成

测试验证

单元测试通过
集成测试通过
性能测试通过
用户测试通过

部署上线

代码提交Git
文档发布
团队培训
正式启用

📝 备注

临时方案（在正式实现前）

在正式实现预留导入管理机制之前，可以使用以下临时方案：

// 临时方案：使用注释标记预留导入
// @reserved(id="AIVAL-001", description="未来可能需要的XXX功能")
// use future_module::Something;

这种方式虽然不够优雅，但至少：

保留了预留意图
不会产生编译警告
可以通过grep搜索所有预留项

后续优化方向

与项目管理工具集成（Jira/GitHub Projects）
自动生成预留路线图
预留依赖关系可视化
AI辅助预留管理

工单创建时间: 2026-02-19 01:00:00 GMT+4
工单创建者: NAC开发团队
工单状态: 待处理
优先级: 中
预计完成时间: 2026-03-10

13 KiB Raw Blame History Unescape Escape