jrcalgo/ciac-compiler

# CIaC — 代码即基础设施编译器 一个 `.ciac` 源文件。生成五个达到生产级质量的后端 —— Python、 Rust、TypeScript、Go、Java —— 它们保持一致性，各自在其 生态系统中符合语言习惯，且每次重新构建时字节完全一致。同一个文件 可以作为*整个系统*的确定性模拟运行，包括 各种故障，并且无需数据库、消息代理或 Docker。`ciac build` 会生成真实的 部署：目前支持 compose，根据需要也可支持 Kubernetes、Terraform 或 CI。 编译器负责管理连接；你的业务逻辑存在于生成的 stub 中，你可以自行编辑，且绝不会被覆盖。 代码基础设施即代码 编译器不是那种你 fork 后就会产生分叉的脚手架模板，也 不是你要部署的 runtime —— 它是一个编译器，你会在系统的整个生命周期中 持续针对源文件运行它。如果这种权衡 不是你想要的，或者你的架构不适合由服务/API/pipeline/stream 组成的 类型化图，那么它就不适合你。 ## 十五分钟，从开始到完成 安装： ``` curl -fsSL https://raw.githubusercontent.com/jrcalgo/ciac-compiler/main/install.sh | sh # 或：cargo install --path crates/ciac （需要 Rust toolchain；约 2 分钟） ``` 搭建项目并查看你得到了什么 —— `ciac new` 会生成 `main.ciac` 以及一个告诉你接下来该运行什么的 README： ``` ciac new my-app && cd my-app && ciac check main.ciac ``` 本演练的其余部分使用了一个稍微大一点的程序 —— 一个 record、免费的 CRUD、一个带有 `transaction` 的 handler、一个 stream、一个 worker —— 已提交到此仓库中，即 [`examples/quickstart.ciac`](examples/quickstart.ciac)，因此它永远不会 与实际编译的内容产生偏差。将其粘贴到你自己的 `main.ciac` 中 以便在 `my-app` 中继续操作，或者克隆此仓库并直接 将下面的命令指向 `examples/quickstart.ciac`： ``` service Notes; use { db Postgres; queue NATS; } record Note { id: Uuid; title: String; body: String; } crud Note: Note; // free CRUD: /notes record ArchiveEvent { id: Uuid; note_id: Uuid; } table ArchiveEvents: ArchiveEvent; stream NoteArchived: Note; handler ArchiveNote(note: Note) -> Note { transaction { db.insert(ArchiveEvents, ArchiveEvent { id: Uuid.new(), note_id: note.id }); } return note; } api ArchiveNoteRoute: Note { method: POST; path: "/notes/archive"; } pipeline ArchiveNoteRoute: ArchiveNote -> publish NoteArchived -> Return; worker LogArchive on NoteArchived { max_retries: 2; } handler RecordArchiveEvent(note: Note) -> Note { return note; } pipeline LogArchive: RecordArchiveEvent; ``` 为其中一个目标构建它 —— 五个中的任意一个： ``` ciac build examples/quickstart.ciac --target python --out ./build ``` 将 `--target python` 换成 `rust`/`typescript`/`go`/`java`，下面的每个 命令依然可以原封不动地运行 —— 这就是一致性声明， 可以通过演示证明，而非仅仅口头 assertion。`./build/app/logic/archive_note.py` 是六行真实、易读的代码 —— 包含 transaction 和返回 值，没有任何编译器需要向你隐藏的东西。 现在，无需启动任何东西即可运行系统 —— 没有 Postgres，没有 NATS， 没有 Docker —— 并向其中注入一个真实的故障： ``` ciac sim examples/quickstart.ciac --target python --out ./build \ --scenario sim/quickstart.ciac-sim.json # [PASS] 29-m3-quickstart ``` 该场景 ([`sim/quickstart.ciac-sim.json`](sim/quickstart.ciac-sim.json)) 让 archive 自身的数据库提交失败一次，断言审计行从未 到达，然后重试，并断言它在第二次确实成功了 —— 这是一个针对真实生成代码的端到端原子性证明，具有确定性， 只需几毫秒。然后确认生成的项目本身是完好的并启动它： ``` ciac verify examples/quickstart.ciac --target python --out ./build ``` ``` ciac dev examples/quickstart.ciac --target python --out ./build ``` `ciac dev` 会监控源文件，重新生成代码，重启 compose 技术栈，并在每次保存时重新探测健康状况。这就是整个循环：一个文件、 五种语言、在单个 container 启动前的真实模拟系统， 以及在你准备好时的真实系统。 ## 全局概览 | CIaC 概念 | Python | Rust | TypeScript | Go | Java | |--------------|--------|------|-------------|-----|------| | API | FastAPI router | Axum router | Fastify plugin | `net/http` `ServeMux` | Spring MVC `@RestController` | | Database | SQLAlchemy async (Postgres/MySQL/SQLite) | SQLx pool | Drizzle + raw SQL | `database/sql` pool | Spring `JdbcClient` | | Queue | nats-py / aiokafka | async-nats / rdkafka | `@nats-io/transport-node` / kafkajs | nats.go / franz-go | jnats / spring-kafka | | Auth | JWT / OAuth2 | JWT / OAuth2 | JWT / OAuth2 | JWT / OAuth2 | JWT / OAuth2 | 上面的每个 provider 都支持在所有五个目标上生成；完整的表格， 每一项功能（缓存、对象存储、电子邮件、搜索、tracing、 指标、调度器、实时通信）以及目标之间已披露的每一项差异都位于 [docs/language.md](docs/language.md) 和 [docs/backends.md](docs/backends.md) 中 —— 这份如实披露的账本本身 就是卖点的一部分，而不是被隐藏起来。 **模拟**比上面的演练要深入得多：完整的关系型和 broker 模拟、虚拟时间、每一个故障注入点，并且 — 自 v0.26 起 —— 可以将整个*多服务*系统（共享 broker、共享 时钟、跨服务 `call`s）作为一个确定性运行进行模拟，支持 所有五个目标。请参阅 [docs/simulation.md](docs/simulation.md)。 **部署**会将构建转换为 compose、Kubernetes 清单 （`--deploy k8s`）、Terraform（`--deploy terraform`），或者完全镜像 `ciac verify` 的 GitHub Actions 工作流（`--deploy ci`）； `ciac verify --system` 会启动真实的 compose 技术栈，并 针对它运行生成的系统测试。请参阅 [docs/deployment.md](docs/deployment.md)。 **演进**是第一方的比较，而不仅仅是文件差异比对： `ciac diff --semantic` 会针对签入的基线，将架构更改分类为 破坏性/新增/内部；`ciac rename` 是具有事务性 重新生成重放机制的、全程序的多文件重命名；而 `ciac backfill plan` 会通过扩展/回填/收缩的阶梯流程来处理破坏性的存储 变更。请参阅 [docs/evolution.md](docs/evolution.md)。 **Agent** 使用这个 CLI 而不是人工操作时，会有其专属的 入口：`ciac describe`（作为单个版本化 JSON 文档的完整词汇表）、 `ciac mcp`（作为 MCP 工具的 check/build/diff/verify/graph/explain/fix）、 以及在每个搭建和构建的项目中生成的 `AGENTS.md`。请参阅 [docs/agents.md](docs/agents.md)。 ## 接下来去哪里 - **正在评估 CIaC？** [docs/positioning.md](docs/positioning.md) 是 与框架、代码生成器和 BaaS 平台的诚实对比 —— 包括 何时不该使用它 —— 并且 [docs/backends.md](docs/backends.md) 的差异账本为其中的每一个比较声明提供了支持。 - **想要构建项目？** [docs/guide/](docs/guide/01-first-service.md) 是一个包含七个指南的系列，它通过一个连续的示例，从第一个 服务一直构建到多服务模拟和部署，每个 指南都在真实的检查点处结束。 [docs/authoring.md](docs/authoring.md)（编辑器设置、`ciac lsp`、 blueprints）和 [docs/dev-loop.md](docs/dev-loop.md)（监控循环） 涵盖了 `ciac build` 之前和期间的操作。 - **完整参考：** [docs/language.md](docs/language.md)（语言 规范） · [docs/expressions.md](docs/expressions.md) （handler 主体、动词、事务） · [docs/blueprints.md](docs/blueprints.md) · [docs/architecture.md](docs/architecture.md) · [docs/ir.md](docs/ir.md) · [docs/external-backends.md](docs/external-backends.md) · [docs/regeneration.md](docs/regeneration.md) · [docs/operations.md](docs/operations.md) · [docs/errors.md](docs/errors.md)。 - **CIaC 是如何发展到这一步的：** [docs/history/history.md](docs/history/history.md) — 这个 README 曾经以此开头的版本更迭故事。 ## 从源码构建 ``` cargo build --release # the compiler cargo test --workspace # unit, golden, negative, determinism tests cargo run -p ciac -- check examples/video-platform.ciac ``` ## 仓库布局 | 路径 | 内容 | |------|----------| | `crates/ciac` | CLI | | `crates/ciac-syntax` / `ciac-ir` / `ciac-sema` | lexer/parser/AST、类型化系统图、验证阶段 | | `crates/ciac-codegen` | `Backend` trait、共享模型、确定性规则 | | `crates/ciac-backend-*` | 每个目标（python、rust、ts、go、java）一个 crate | | `crates/ciac-sim` | 确定性模拟 runtime | | `examples/` | 有效的示例程序，`sim/` 包含其场景 | | `editors/` | 用于 `.ciac` 的 TextMate 语法 + VS Code 扩展 | | `tests/` | golden 快照、负面测试套件、确定性测试 | | `docs/` | 参考文档和指南系列 —— 请参阅 [docs/README.md](docs/README.md) 获取完整索引 | ## License Apache-2.0

标签：JS文件枚举, 代码生成, 可视化界面, 后端架构, 子域名突变, 日志审计, 渗透测试工具, 版权保护, 编译器, 逆向工具, 通知系统, 领域特定语言