bisql

# bisql bisql 是一个用于 Go 的双向 SQL 模板引擎。它允许你编写同时是有效 SQL 语句（可在 SQL 客户端中执行）和应用程序参数化查询构建器的 SQL 模板。指令以 SQL 注释形式表达，因此同一文本在两种上下文中均适用。 ## 主要特性 - **双向 SQL**：模板是有效的 SQL；指令是注释。同一文本可在客户端中运行（使用示例值），并在 Go 中构建参数化语句 `(SQL, Args)`。 - **显式模型**：不隐式移除空子句或悬空连接符。作者需锚定动态片段（例如 `1 = 1`）以获得可预测的输出。 - **指令**：绑定（`/* expr */literal`）、字面量插值（`/*^ expr */literal`）、条件（`/*%if*/`、`/*%elseif*/`、`/*%else*/`、`/*%end*/`）、循环（`/*%for x in xs*/`）以及包含（`/*%! @include name */`）。 - **片段包含**：通过 `@include` 组合可复用的 SQL 片段，从 `fs.FS`、内存注册表或自定义加载器解析。支持递归，并带有循环/深度保护。 - **方言支持**：为 MySQL、SQLite、PostgreSQL、Oracle 和 SQL Server 生成占位符。支持 PostgreSQL 的数组绑定。 - **表达式语言**：使用 expr-lang 处理条件和可迭代对象，支持比较、逻辑运算、可选链、空值合并、`in` 和 `len`。 - **安全设计**：不对任意值进行原始文本替换；动态标识符必须通过 `/*%if*/` 分支白名单化。 ## 用法 模板是 `.sql` 文件。使用 `ParseFile` 从任何 `fs.FS`（例如嵌入的）解析，然后使用参数映射或结构体构建。 ```go p := bisql.NewParser(bisql.WithDialect(dialect.PostgreSQL)) tmpl, err := p.ParseFile(sqlFS, "users/search.sql") stmt, err := tmpl.Build(map[string]any{"name": "Alice", "activeOnly": true, "status": "active"}) fmt.Println(stmt.SQL) // 参数化 SQL fmt.Println(stmt.Args) // 绑定参数 ``` ## 编写规则 - 锚定动态片段（例如 `AND` 链使用 `1 = 1`，`OR` 链使用 `1 = 0`）。 - 对于列表，使用前导连接符（`and`/`or`）或从零行种子开始使用 `union all select` 处理逗号列表。 - 使用 SQL 标准双写来引用字符串/标识符；不支持反斜杠转义。 - 使用 `/*%! … */` 作为解析器注释（移除）或 `/** … */` 作为普通块注释。 ## 包结构 - `bisql`：公共 API（Parser、Parse、Expand、加载器）。 - `dialect/`：方言定义。 - `expr/`：求值器接口和 Scope。 - `internal/`：模板层和默认求值器。 ## 开发 工具链固定在 `mise.toml` 中；运行 `mise run check` 进行格式化、构建、vet、lint 和测试。PostgreSQL 集成测试需要构建标签和 DSN。 完整文档请参阅 [Go Reference](https://pkg.go.dev/github.com/mpyw/bisql)。