Skip to content

Web 与 SQLite ​

SDK 里带着两个库:写 HTTP 服务的 libraries/sprig-web,和操作 SQLite 数据库的 libraries/sprig-sqlite。还有几个用到它们的示例项目:examples/mini_web、examples/sqlite、examples/sqlite_migrations 和 examples/ledger。

这些都是实验性的示例,用来展示 Sprig 能做到什么程度,不是可以直接用于生产环境的框架。

跑起记账后端 ​

examples/ledger 是一个完整的记账后端,有 HTTP 接口和 SQLite 存储,还会自动生成接口文档。在已经构建好的 Sprig 仓库根目录下运行:

bash
cd examples/ledger
../../bin/sprig resolve
../../bin/sprig check --offline
../../bin/sprig run --offline -- ledger.sqlite 8080

看到 LEDGER_READY 8080,服务就启动好了。打开 http://localhost:8080/docs 可以在 Swagger UI 里试接口,/openapi.json 是机器可读的接口描述。Swagger 页面要从 CDN 加载资源,所以需要联网;后端本身只监听本机地址,依赖解析并缓存好以后完全可以离线运行。按 Ctrl+C 停止。

在 VS Code 里,这种一直运行的程序要用 Sprig: Run in Terminal 来运行。

方法路径作用
GET、POST/api/accounts列出、新建账户
GET、POST/api/categories列出、新建分类
GET、POST/api/transactions列出、新建交易
DELETE/api/transactions/{id}删除一笔交易,删除成功返回 204,不存在返回 404
GET/api/statistics/monthly?month=2026-09某个月的交易笔数和收支统计

金额用整数表示,单位是最小的货币单位(比如「分」),可以是负数。请求字段、存储和校验规则见 ledger 的 README(英文)。

处理函数就是普通的 Sprig 函数 ​

每个路由的处理函数,类型都是 fn(web.Request) -> web.Response throws Error,规则只有一条:想让客户端看到的回答,不管是 404,还是说明哪个字段不对的 400,都用你返回的 Response 表达;没处理的错误就让它抛出去,交给服务器回答。下面这几段摘自 examples/mini_web/src/main.spr:

sprig
import "@web/web.spr" as web

let app = web.App(title="Mini Web", cors_origin="http://localhost:5173")

func root(req: web.Request) -> web.Response:
    return web.text("Hello, Sprig!", 200).with_header("X-Sprig", "mini-web")

func hello(req: web.Request) -> web.Response:
    let name = req.path_param("name")
    let greeting = req.query("greeting")
    if name != null:
        if greeting != null:
            return web.text(greeting + ", " + name + "!", 200)
        return web.text("Hello, " + name + "!", 200)
    return web.text("Missing name", 400)

func echo(req: web.Request) -> web.Response throws Error:
    return web.json_response(req.json(), 200)

app.get("/", fn(req: web.Request) => root(req))
  • 用 app.get、app.post、app.put、app.patch、app.delete 注册处理函数。app.run(port) 只监听本机 127.0.0.1;要让别的机器或容器外部访问,用 app.run_on("0.0.0.0", port)(没有 TLS,需要的话前面放一个反向代理)。如果还想生成接口文档,就用 app.route 传一个 web.Route,在里面写明摘要,以及参数、请求和响应的结构。没有装饰器,也没有 Java 注解。
  • 响应用模块函数来构造:web.text(内容, 状态码) 和 web.json_response(值, 状态码)。没有 Response.text 这种静态方法的写法。
  • req.path_param、req.query、req.header 都返回 String?,所以「没有这个参数」和「参数是空字符串」能区分开。
  • req.body 是 UTF-8 文本,req.json() 把请求体解析成 JSON 值。要在 JSON 里找字段,用 json.find_member,它能区分键不存在、值是 JSON 的 null,以及要查的不是对象这几种情况,见语言速查。
  • 请求体不是合法的 JSON 时,req.json() 会抛出 Error;web.json_response 遇到写不成 JSON 的值,也会抛出 Error。客户端只需要知道“请求不对”时,就像上面的 echo 一样声明 throws Error,让它抛出去;要告诉对方具体哪里不对,就自己返回一个 400 的 Response。不要只为了返回一个笼统的 400 或 500 去捕获错误,服务器会做这件事。
  • 请求格式不对时返回 400(req.json() 解析失败、处理函数又把错误抛了出去,也是 400),找不到路由时返回 404,处理函数抛出的其他错误,返回一个受控的 500。

接口文档 ​

OpenAPI 文档来自你明确写出的 Schema、FieldSchema、QueryParameter 这些值,库不会去反射任意的类。这些描述只是文档,请求里的值仍然要在处理函数里自己校验。注册路由时,重复的查询参数和互相冲突的路径模板会直接报错。

完整的行为说明见 libraries/sprig-web/README.md(英文)。运行 sprig resolve 之后,可以用 sprig api @web/app.spr --json 查看这个库所有接口的签名。

SQL 写在明处 ​

SQLite 库通过 Maven 拿到固定版本的 org.xerial:sqlite-jdbc:3.46.1.0,具体文件记录在锁文件里。

  • SQL 语句就是你写的普通字符串,算作可信的应用代码。用户提供的值一律通过预编译语句的参数传进去,参数只有 Integer、Text、Boolean、Null 四种。这不是 SQL 沙箱。
  • 每个 SQL 字符串只能写一条语句。末尾带分号或注释没关系;多写一条会直接报错,不会被悄悄跳过。有多条语句的脚本,写成迁移文件。
  • 查询返回的是带类型的结果快照,已经和数据库连接断开。连接、语句和结果集用完都会关闭。单次查询的结果最多 10,000 行,超过会报错;结果会整个读进内存。
  • Database.batch 在一个事务里执行一组语句,任何一条失败就全部回滚。查询(包括 INSERT ... RETURNING)失败时,它写进去的数据也会回滚。
  • sqlite.transaction(database, callback) 支持“读取、检查、写入”:回调接收 Transaction,它的 query 和 execute 共用一个连接,能看到前面尚未提交的写入。成功后提交并返回回调结果;回调抛出 Error 或 SQL 操作失败会回滚,保留 JDBC 原因和原始错误。即使回调捕获 SQL 操作的错误,也不会提交。
  • 事务只在同步回调内部、同一线程上有效;回调结束后使用会抛出 Error。不支持嵌套事务和保存点。回调里始终使用传入的 Transaction:直接调用数据库本身的方法(database.query、execute、batch)会立刻抛出 Error,因为那会另开一个连接,看不到事务里还没提交的写入。回调没有返回值时,用 sqlite.transaction_run(database, callback)。已脱离连接的 Rows 可以返回并继续读取。
  • 不能自行执行 BEGIN、COMMIT 等事务控制语句;提交、回滚和资源关闭由库管理。可运行的例子见账户转账。
  • 没有 ORM,不会把 REAL 自动转成 Int,也不支持 BLOB 和 Decimal 参数。只支持普通的数据库文件,不支持 :memory: 内存数据库。

数据库迁移(实验性) ​

导入 @sqlite/migrations.spr,然后调用 Migrations(database=database, directory="migrations").apply():

  • 迁移文件命名为 NNN_description.sql,开头的三位编号不能重复。
  • 文件按文件名顺序执行,执行过的文件名记在 sprig_schema_migrations 表里。执行任何文件之前,apply() 会先拿整个目录和这张表核对:文件名不合规、编号重复,或者已经执行过的文件排在还没执行的文件后面,都会直接报错,一个文件也不执行。
  • 每个文件里的 SQL 和它的执行记录在同一个事务里提交。失败就一起回滚,修好以后可以再次执行。
  • 已经执行过的文件不要再改:目前不会计算文件内容的校验值,改了也发现不了。迁移目录被当作可信的项目代码。

完整的例子见 examples/sqlite_migrations,所有接口见 libraries/sprig-sqlite/README.md(英文)。

限制 ​

这是一个同步、单用户的示例,没有登录认证、会话、连接池和异步处理,也没有考虑公网部署。请求体和查询结果都会整个读进内存。类型检查能保证类型正确,但保证不了业务规则和数值计算是对的。

怎么验证的 ​

仓库里的测试会启动真正的本机 HTTP 服务,用临时的 SQLite 文件读写,检查重启之后数据还在不在,并核对 OpenAPI 文档的结构:

bash
python3 tests/callables/check_callables.py
python3 tests/web/check_web.py
python3 tests/sqlite/check_sqlite.py
./scripts/verify.sh

开发过程的记录在 docs/history/milestones/WEB_SQLITE_ENGINEERING_REPORT.md。想写由多个文件组成、带选项解析的命令行工具,可以参考 examples/json_select。

Sprig 采用 Apache-2.0 许可证 · v0.7.1-beta.1 已作为 prerelease 发布