直接讲，数据服务这个词已经被聊烂了，但真把“SQL 即接口”这套落地的开源项目凤毛麟角。SqlRest 1.6 正是这类项目里比较能打的一个，而这次我在 IDEA 里跑的，是它的 PostgreSQL 适配版。简单说，它让你不用写 Controller、Service、Mapper，只需要维护 SQL 映射配置，就能把数据库查询以 RESTful 接口的形式暴露出去，配合 pg 的 JSON、窗口函数等特性，做数据服务层非常顺手。这篇文章我会把 1.6 pg 版从环境准备、配置解析到启动联调的完整过程写清楚，包括我踩过的坑和排查思路，给准备在 IDEA 里把它跑起来的人一份可直接照抄的作业。
1. SqlRest 1.6 项目全貌与核心价值拆解
1.1 它到底解决什么问题：数据服务的本质是“SQL 即 API”
传统 Java Web 项目做一个查询接口，流程通常是：Controller 接收参数、Service 组织业务逻辑、Mapper 写 SQL、再手动把 ResultSet 转成 JSON 返回。这个链路本身没问题，但对于大量“只读查询、报表输出、数据大屏、临时分析”这类场景，它明显重了：一个普通列表查询就要新建三四层类，而且每加一个字段都要重新编译、重新部署。
SqlRest 的核心思路是砍掉中间层，把 SQL 本身作为接口定义。你在配置文件里写一段带占位符的 SQL，声明好 URL、参数、返回格式，启动后框架自动完成参数绑定、SQL 执行、结果集转 JSON 的流程。pg 版则在此基础上针对 PostgreSQL 数据库做了适配，重点体现在几个方面：pg 的类型系统更丰富（数组、JSONB、几何类型），框架在结果集映射时需要更细致的类型转换；同时 pg 的RETURNING、窗口函数、LATERAL等特性在 SqlRest 的动态 SQL 里可以直接透传使用，灵活性比 MySQL 版更高。
这意味着什么？意味着你的 SQL 能力直接转化为接口产出速度。一张业务表要开放查询，从写 SQL 到接口可用，往往只需要几分钟，而且不需要重启应用——修改配置后自动热加载。对数据部门、后端团队做内部数据服务、对前端低代码平台做数据源对接，这个模式非常合适。
1.2 为什么 1.6 和 pg 版值得单独拿出来说
SqlRest 1.6 之前的版本，更多像是一个“SQL 执行器”，对参数校验、事务控制、多数据源、接口鉴权这些生产级问题覆盖不够。1.6 算是把数据服务化的框架雏形补齐了：支持多数据源动态切换，支持接口级 token 校验，SQL 映射规则也做了全面梳理，关键字冲突、复杂嵌套查询的处理比旧版稳很多。pg 版则是在这个基础上，把默认方言、驱动适配、类型映射全部切到 PostgreSQL 体系，并且针对 pg 的 schema 机制做了优化，多 schema 场景下查询指定 schema 更容易。
从我实际使用看，pg 版的关键优势集中在三个场景：第一，PostgreSQL 的 JSONB 字段可以直接在 SQL 里做->>操作，SqlRest 返回结果时能把 JSONB 原样序列化给前端，省掉一层 DTO 转换；第二，pg 视图和物化视图非常成熟，很多报表类接口可以直接建立在物化视图之上，配合 SqlRest 的定时刷新或按需刷新，数据服务层的查询性能很好把控；第三，pg 的pg_stat_statements、EXPLAIN ANALYZE配合 SqlRest 打开慢查询日志，排查线上接口问题非常顺畅。
1.3 谁适合阅读这篇文章
如果你是后端开发、数据开发，或者在做数据中台、数据服务网关这类方向，这篇文章可以帮你把 SqlRest 1.6 pg 版在本地 IDEA 环境里完整跑通。如果你只是临时需要把一个 pg 库的表开放成接口给同事调用，同样适用——不需要深入框架源码，只需要跟着配置走。文章不会贴全部源码，但关键的配置文件、启动参数、接口调用格式、报错排查都会讲全。建议你本地准备一个 PostgreSQL 实例，版本 12 以上即可，跟着实操部分同步跑一遍，比我干讲有用得多。
2. IDEA 启动前的环境准备与项目导入
2.1 本地环境清单：JDK、Maven、Git 一个都不能少
SqlRest 1.6 是基于 Spring Boot 2.x 构建的，所以本地 JDK 必须保证 1.8 以上，我建议直接用 JDK 8 或者 JDK 11。用太高版本比如 JDK 17 不是不行，但 Spring Boot 2.x 对高版本 JDK 的兼容性需要额外关注，实际跑的时候容易碰到反射相关的警告，能避就避开。Maven 建议 3.6.3 以上，IDEA 2020 之后的版本内置 Maven 也可以，但最好还是用独立安装的 Maven，方便统一 settings.xml 里的镜像配置。
Git 是拉取代码用的，这个没什么好说的。如果你本地有代理或者公司网络比较特殊，记得先确认 git clone 能正常访问 GitHub。SqlRest 的仓库是公开的，直接把项目 clone 到本地工作目录即可。我这里多说一句，clone 下来之后不建议直接修改根目录的 pom.xml 里的版本号，因为你改了一个版本号，往往会牵连其他依赖的版本兼容问题，不如保持原样。
还有一个很容易被忽略的点：IDEA 的编码设置。SqlRest 源码里有中文注释和资源文件，IDE 默认编码如果不是 UTF-8，会出现注释乱码，更严重的会导致 properties 文件里的中文配置解析失败。建议在 IDEA 的 Settings -> Editor -> File Encodings 里把 Global Encoding、Project Encoding、Default encoding for properties 全部设为 UTF-8，并勾选 Transparent native-to-ascii conversion。这个小设置能省掉后续很多莫名其妙的编码报错。
2.2 PostgreSQL 本地实例与初始化数据准备
pg 版启动前，你需要有一个能连上的 PostgreSQL。本地没装的话，去官网下载对应系统的安装包，装的时候记住端口号，默认 5432，超级用户 postgres 的密码自己设好。装完之后建议再创建一个专门的数据库，比如sqlrest_demo，不要直接拿默认的 postgres 库来跑，避免权限和连接串混乱。
CREATE DATABASE sqlrest_demo ENCODING 'UTF8';创建完数据库之后，需要初始化一张测试表。SqlRest 本身不强依赖特定表结构，但你要验证查询接口，总得有数据可查。这里我建一张简单的用户表和一张订单表，方便后面演示多数据源和关联查询：
CREATE TABLE sys_user ( id BIGSERIAL PRIMARY KEY, name VARCHAR(50) NOT NULL, org_id BIGINT, status SMALLINT DEFAULT 1, create_time TIMESTAMP DEFAULT NOW() ); COMMENT ON TABLE sys_user IS '用户表'; INSERT INTO sys_user (name, org_id, status) VALUES ('张伟', 1001, 1), ('李娜', 1002, 1), ('王强', 1001, 0), ('赵敏', 1003, 1);这里用BIGSERIAL而不是自增INT，主要是 pg 的习惯，同时TIMESTAMP类型在 SqlRest 里做范围查询时表现很稳定。初始化完成后，建议先用 psql 或者 Navicat 试一下连接串，确认密码、库名、端口都没问题，因为启动阶段 90% 的报错都集中在数据库连接上。
2.3 IDEA 导入项目与 Maven 依赖拉取的三个要点
IDEA 打开项目的方式很简单：File -> Open，选择 clone 下来的 SqlRest 目录，等 IDEA 识别成 Maven 项目即可。但这个过程中有几个点要注意。
第一，Maven 仓库镜像。国内网络直接从 Maven Central 拉依赖比较慢，而且容易拉到一半超时。建议在 Maven 的 settings.xml 里配置阿里云镜像：
<mirror> <id>aliyunmaven</id> <mirrorOf>central</mirrorOf> <name>Aliyun Maven Mirror</name> <url>https://maven.aliyun.com/repository/public</url> </mirror>配置完成后在 IDEA 里 File -> Settings -> Build Tools -> Maven，把 Maven home path 指向你本地 Maven 安装目录，User settings file 指向 settings.xml。这块配好，依赖拉取基本 10 分钟内搞定。
第二，IDEA 的 Lombok 插件。SqlRest 项目用了 Lombok 来简化实体类代码，如果你没装插件，编译阶段会报找不到log、找不到getter/setter这类错误。在 IDEA 插件市场直接搜 Lombok 安装，重启 IDE 即可。这点很容易被忽略，因为 Maven 依赖明明加载成功了，为什么编译报错？就是注解处理器没有在 IDE 里生效。
第三，JDK 与 Maven 的版本要在 IDEA 的 Project Structure 里确认一致。经常有人 Maven 用的是 JDK 17，项目编译却选了 JDK 8，最后出现Unsupported major.minor version 52.0这种错。统一到同一个 JDK 版本，最好直接设置 IDEA 的 Gradle/Maven JVM 为同一个路径。
3. pg 版核心配置解析与启动实操
3.1 application.yml 里的关键配置逐项拆解
SqlRest 的配置集中在src/main/resources/application.yml。pg 版与 MySQL 版的差异主要就在数据源配置和方言配置这一段。我直接把我能跑通的配置贴出来，并逐项说明：
server: port: 8080 servlet: context-path: /sqlrest spring: application: name: sqlrest datasource: url: jdbc:postgresql://127.0.0.1:5432/sqlrest_demo username: postgres password: your_password driver-class-name: org.postgresql.Driver hikari: minimum-idle: 5 maximum-pool-size: 20 connection-timeout: 30000 sqlrest: enable: true base-package: com.sqlrest.demo token-enabled: false slow-sql-millis: 1000server.port和context-path决定了接口根路径。context-path设成/sqlrest的好处是后续启动的接口文档、接口调用都有一个统一前缀，不容易和同机器其他应用冲突。spring.datasource这一段是 pg 版的核心，url 里注意是jdbc:postgresql://，驱动类是org.postgresql.Driver，这两个地方写错是最常见的启动失败原因。
sqlrest.enable是总开关，一定要为 true。base-package是 SqlRest 扫描 SQL 映射配置的包路径，默认可以指向你新建的配置文件包。token-enabled我建议开发阶段设成 false，省去每个请求带 token 的麻烦，等真正部署再开。slow-sql-millis是慢 SQL 阈值，超过 1000ms 会打印告警日志，后期排查性能问题非常有用。
有一点需要特别提醒：HikariCP 连接池的maximum-pool-size在 pg 上建议不要太大，一般 20 就够。pg 的每个连接都是独立进程，连接数太多会浪费服务端内存，而且容易出现sorry, too many clients already错误。这个错误不是连接池配置错了，而是 PostgreSQL 默认max_connections = 100，多个应用共享同一个实例时很容易打满。
3.2 SQL 映射配置的写法与参数绑定规则
SqlRest 的映射文件通常放在资源配置目录下，比如resources/sqlrest/下，文件名对应一个分组。我以一个简单的用户查询为例说明格式：
sqlrest: mappings: - id: user_list sql: | SELECT id, name, org_id, status, create_time FROM sys_user WHERE 1 = 1 { and id = #{id} } { and name like concat('%', #{name}, '%') } ORDER BY id DESC pageable: true fields: id: java.lang.Long name: java.lang.String org_id: java.lang.Long status: java.lang.Integer create_time: java.time.LocalDateTime这里要讲清楚 SqlRest 的 SQL 占位符规则：#{参数名}是基础绑定，框架在解析时会把对应值替换成?占位符，由 PreparedStatement 执行，天然防 SQL 注入。同时支持{}块和 where 条件拼接，当参数为空时，整个语句块会被移除，这就实现了动态 SQL 的“有值则过滤、无值则不过滤”的效果。
pageable: true表示接口支持分页，请求时传page和rows两个参数，框架会自动包裹一层LIMIT/OFFSET查询。对 pg 来说，LIMIT/OFFSET 是原生支持的，大数据量场景下可以用 keyset pagination 优化，但 SqlRest 默认的分页已经能满足绝大多数报表场景。
还有fields字段的声明，它主要是给接口文档和类型转换用的。你可能会问，不声明行不行？实验下来，查询结果太少时框架可以自动推断类型，但如果查询结果为空，类型推断就无从下手，接口会返回空数组导致前端拿到结构不一致。所以建议正式使用的查询都把 fields 写清楚。
3.3 主启动类与 IDEA 运行配置的细节
SqlRest 的启动类一般叫SqlRestApplication，标准 Spring Boot 写法。在 IDEA 里直接右键运行 main 方法是最简单的，但为了调试方便，我建议你创建一个 Run/Debug Configuration：Main class 选SqlRestApplication，VM options 建议加上-Dfile.encoding=UTF-8，Working directory 默认项目根目录即可。
启动后你会看到 Spring Boot 的 Banner，紧接着是连接池初始化和映射文件解析日志。重点看这几行日志：
SqlRest mapping loaded: user_list SqlRest service startup completed in 1.235s出现这两行，说明映射加载成功。如果映射 SQL 写错了，报错通常在启动阶段而不是接口调用阶段。SqlRest 解析 SQL 挺“聪明”的，不匹配的括号、错误的占位符它都能抛出来，但是语法层面的错误它感知不到——比如你写了WHERE FROM这种，启动不会报错，要到接口真正执行时才报数据库异常。所以第一次跑通后，建议先用简单 SQL 验证链路，再逐步上复杂查询。
如果你用的是社区版 IDEA，没有 Spring Boot 运行类型也没关系，直接右键 main 方法运行就行。不需要额外装 Spring Assistant 插件，SqlRest 不依赖那些 IDE 层面的花活。
4. 启动后验证与接口联调
4.1 接口文档页面与服务列表的访问方式
SqlRest 1.6 内置了一个简易的管理页面，启动后访问：
http://localhost:8080/sqlrest/doc.html如果你是默认配置且没有设置 context-path，就是：
http://localhost:8080/sqlrest/doc.html这个页面会列出所有已加载的 SQL 映射 ID，点击可以查看对应的参数说明和 SQL 内容。它不像 Swagger 那样能直接做在线调试，但用来确认“这个映射加载了吗”“SQL 是什么样”很方便。生产环境建议关掉或者做权限控制，不然等于把内部 SQL 泄露给所有人，非常危险。
如果页面打不开，先别急着怀疑配置，检查一下 context-path 是不是写成了/sqlrest/，结尾多一个斜杠在某些版本中会导致静态资源路径错误。另外 IDEA 启动日志里会有Tomcat started on port(s): 8080和context path: '/sqlrest'，确认这两条信息，就能判断是配置问题还是端口问题。
4.2 标准接口调用格式与返回结构
接口调用格式是/{映射ID}，参数通过 GET 或 POST 传递。以 user_list 为例：
GET http://localhost:8080/sqlrest/user_list?id=1返回 JSON 结构大概是这样的：
{ "code": 0, "msg": "success", "count": 1, "data": [ { "id": 1, "name": "张伟", "org_id": 1001, "status": 1, "create_time": "2025-01-15 10:30:00" } ] }code: 0表示成功，非 0 时msg里是错误信息。count是总记录数，data是具体数据数组。这个结构和大多数前端框架的数据请求封装能直接对齐，不需要再包一层。这里有一个细节：如果映射里没有开启pageable，count字段默认等于 1，不要误以为是查询到的行数。
分页请求的格式是：
GET http://localhost:8080/sqlrest/user_list?page=1&rows=20page从 1 开始，rows是每页条数，我建议前端约定好后固定传，不要缺省。缺省时不同版本的默认值不一样，容易产生歧义。
4.3 动态 SQL、JSONB 与 pg 特有类型的实战用法
pg 版的一个亮点是可以直接在 SQL 映射里使用 PostgreSQL 独有特性。拿 JSONB 举例：
- id: order_search sql: | SELECT id, payload, payload ->> 'customer' AS customer_name FROM order_event WHERE 1 = 1 { and payload ->> 'customer' = #{customer_name} } { and (payload ->> 'amount')::numeric >= #{min_amount} } ORDER BY id DESC这里payload ->> 'customer'是 pg 的 JSONB 取值语法，SqlRest 在解析时不会干扰这部分，直接透传给 pg 执行。返回结果里customer_name就是 JSON 中的字符串，amount字段强转 numeric 后参与比较。这种查询放在传统 Java 服务层写起来很别扭，但在 SqlRest 里只是 SQL 本身的事，非常爽。
还有数组类型的参数，pg 原生支持数组，SqlRest 的占位符也能适配：
{ and id = ANY(#{ids}::bigint[]) }请求时ids传1,2,3，框架会绑定为字符串，但通过::bigint[]在数据库侧完成类型转换。我实测下来这个写法在 SqlRest 上是能跑的，但要注意参数解析的细节：SQL 里的#{ids}会被替换为 JDBC 占位符，数组参数的 setObject 会由 pg 驱动识别成Array类型。如果你传递的字符串确实有空格，建议先 trim，不然转换会报错。
4.4 多数据源配置：pg 与 mysql 同时挂的场景
1.6 版支持多数据源配置，这在数据服务层很实用。很多团队的现状是主库 MySQL、分析库 PostgreSQL，或者不同业务域用了不同的 pg 实例。SqlRest 的多数据源可以在配置里按名称区分配：
sqlrest: datasources: pg_primary: url: jdbc:postgresql://127.0.0.1:5432/sqlrest_demo username: postgres password: your_password pg_readonly: url: jdbc:postgresql://10.0.0.20:5432/analytics username: readonly_user password: readonly_pass然后每个映射声明自己用哪个数据源：
- id: report_daily datasource: pg_readonly sql: | SELECT * FROM daily_report WHERE report_date = #{date}这个能力的价值在于：读写分离后，报表查询全部走只读库，业务库压力直线下降；同时不同逻辑库的表可以在同一个逻辑下暴露接口，不用再为每个库单独部署一个服务。配置时要注意的是，sqlrest.datasources下的连接池参数是独立维护的，不要指望它继承spring.datasource.hikari的全局设置，每个数据源要重复写连接池参数，或者通过 Spring Boot 的配置项统一管理。
5. 常见问题与排查实录
5.1 端口占用与 context-path 404 的坑
最典型的启动报错是：
Web server failed to start. Port 8080 was already in use.这种情况不一定是 8080 被占，而是你已经开了一个实例没关掉，或者本机其他程序占了端口。我的习惯是启动前先看一眼 IDEA 的 Services 面板，把上一个运行实例停掉。更好的做法是在 IDEA 启动配置里勾选Single instance only，避免重复启动。如果端口确实被其他进程占用，那就换端口配置。但换端口之后要注意 doc 页面和接口调用地址也要跟着换。
启动成功但访问文档页 404，九个里有八个是 context-path 没弄明白。我见过有人配置context-path: /sqlrest，但访问地址写的是http://localhost:8080/sqlrest/，多一个斜杠在某些代理环境下就是 404，直接去掉尾斜杠。还有一个原因是 Spring Boot 2.6 之后对静态资源映射规则做了调整，虽然 SqlRest 做了兼容，但如果你自己改过spring.mvc.pathmatch之类的配置可能导致异常，这个要保持默认。
5.2 PostgreSQL 连接失败：时区、驱动、权限三大问题
pg 连接失败是最高频的问题，报错基本分三类。
第一，The connection attempt failed.或者Connection refused. Check that the hostname and port are correct。这是 pg 服务没起或者端口不对。先用psql -h 127.0.0.1 -p 5432 -U postgres测试本地连接，psql 能连上，SqlRest 一定能连上，如果 psql 都连不上，先从数据库侧排查。
第二，Failed to load driver class org.postgresql.Driver。这是 Maven 依赖缺失或者依赖冲突。确认 pom.xml 里有没有 pg 驱动依赖：
<dependency> <groupId>org.postgresql</groupId> <artifactId>postgresql</artifactId> <scope>runtime</scope> </dependency>注意版本，Spring Boot 2.x 管理的默认 pg 驱动版本通常够用，但如果你的 pg 服务器是 15/16，建议显式升级到 42.6.x 以上，老驱动连新 pg 有时会出现The server requested password-based authentication或者协商协议失败。
第三，时区相关的报错The server time zone value 'GMT+8' is unrecognized。这个在 MySQL 上很常见，pg 也会遇到，尤其是在连接串里没有指定时区时。解决方案是在 JDBC URL 后面加上参数：
url: jdbc:postgresql://127.0.0.1:5432/sqlrest_demo?stringtype=unspecified&serverTimezone=Asia/Shanghai另外注意stringtype=unspecified这个参数，它能让 pg 驱动自动处理字符串和类型转换，对 SqlRest 这种以字符串方式传参的框架非常友好。我建议本地开发统一加上这两个参数，能减少大量类型转换报错。
5.3 Maven 依赖冲突与 IDEA 缓存问题
依赖冲突的典型表现是：编译一切正常，运行时报NoClassDefFoundError或者NoSuchMethodError。以 SqlRest 为例，它内部用了 Spring 的RestTemplate、HttpMessageConverter等组件，如果你在 pom 里手动引入了不同版本的 Spring，就会出问题。
我的排查套路是这样：先看 IDEA 的 Maven 面板左侧的 Dependencies，点开对比版本；再执行mvn dependency:tree看冲突依赖。SqlRest 本身是单模块项目，依赖冲突概率不大，但如果你自己加了 JSON 库、Guava、Apache Commons 这类工具库，就要小心版本冲突了。
mvn dependency:tree -Dincludes=com.fasterxml.jackson.core这类命令可以快速定位。一般来说 jackson 的版本冲突最容易踩，因为 Spring Boot 默认自带 jackson。解决方式是在 pom.xml 里用dependencyManagement统一版本或排除传递依赖。
IDEA 缓存问题是另一个隐性杀手。改了 pom 之后 IDEA 经常报找不到某个类，实际上代码没问题。处理方式：File -> Invalidate Caches / Restart，然后重新加载 Maven 项目。这个方法虽然听起来简单，但实测能解决 90% 的“代码没问题 IDE 报错”问题，不要嫌麻烦。
5.4 查询结果序列化：日期格式和 null 值
跑通过几个接口后，你大概率会遇到返回值格式不符合预期的问题。最常见的有两个。
一个是日期格式。pg 的TIMESTAMP映射到 Java 的LocalDateTime后，Jackson 默认序列化格式往往是2025-01-15T10:30:00，但前端通常要2025-01-15 10:30:00。我的解决办法是在 application.yml 里设全局日期格式：
spring: jackson: date-format: yyyy-MM-dd HH:mm:ss time-zone: GMT+8或者针对单个字段在映射 SQL 里直接转字符串：to_char(create_time, 'yyyy-MM-dd HH:mm:ss') AS create_time。第二个方案更直接，也避免前端时区混乱。
另一个是 null 值的处理。Jackson 默认会把 null 字段也输出，前端处理多一个判断。如果你想让返回 JSON 里不出现 null 字段，可以设置：
spring: jackson: default-property-inclusion: non_null但这个全局配置会影响所有接口，如果有些接口就是希望前端看到“字段存在但值是 null”，那就要在 SQL 层用COALESCE或者jsonb_build_object来控制。这个要看你自己团队的接口规范，没有标准答案。
5.5 常见问题速查表
我把这段时间实操下来的高频问题和解决方式整理成一张表，方便你遇到问题时直接对照。
| 现象 | 可能原因 | 解决方案 |
|---|---|---|
| 启动时端口占用 | 已有实例未关闭或端口被其他程序占用 | 停掉旧实例，或修改 server.port |
/doc.html404 | context-path 尾部斜杠、映射资源未加载 | 确认路径无尾斜杠，检查加载日志 |
| 数据库连不上 | pg 服务未启动、端口错、驱动缺失 | psql 手动测试，补 pg 驱动依赖 |
too many clients already | 连接池过大或实例太多 | 调小 maximum-pool-size，关闭无用连接 |
| 日期格式不对 | Jackson 默认 ISO 格式 | 配置 spring.jackson.date-format |
| 传参查询无结果 | 参数类型和 SQL 类型不匹配 | pg 侧加::bigint等显式类型转换 |
| 修改 SQL 不生效 | 映射缓存未刷新 | 确认热加载配置，或重启应用 |
| Maven 依赖找不到类 | 缓存冲突或版本冲突 | Invalidate Caches，mvn dependency:tree 排查 |
这张表不用背，遇到问题再回来看就行。
6. 实操心得与扩展方向
6.1 我踩过的一些坑和最终的用法习惯
第一次跑通 SqlRest pg 版，我最大的感受是：这个东西上手快，但要把配置习惯练好，否则后期维护会乱。SQL 映射文件膨胀速度快得惊人，一两个月就能积累几百个映射 ID。如果不约定命名规范，后面根本找不到哪个 SQL 对应哪个接口。
我的个人习惯是：映射分文件管理，按业务域拆开，user-query.yml、order-report.yml，每个文件内部再按功能分 ID 前缀。user_query_list这种命名比query1清晰得多。另外，基础的数据字典查询和核心报表查询要分开目录放，因为它们的更新频率、权限控制策略都不同。
关于热加载，SqlRest 支持修改映射后不重启生效，但我在 IDEA 里实测有时候会不触发。如果你发现改了配置但接口行为没变，先看日志有没有Mapping file changed, reloading之类的输出。没有的话就老实重启应用，开发阶段多花几十秒，总比哪次生产环境热加载没生效导致的“线上配置和预期不一致”要好。
6.2 事务、安全与监控的扩展姿势
SqlRest 1.6 对写操作支持有限，主要强在读查询上。如果你的数据服务层有“查出来算完写回去”这种简单写操作，可以借助 pg 的存储过程或函数来实现：把复杂逻辑封装在 pg 函数里，SqlRest 映射里调用SELECT * FROM some_proc(...)即可。但更严谨的做法是，写操作还是走传统业务服务，SqlRest 只负责读侧的数据服务化。这样职责清晰，出了问题也好定位。
安全方面，虽然开发阶段我把 token-enabled 设成了 false，但生产环境强烈建议打开，并且至少做到接口级 token 绑定。如果你有统一网关，更推荐的方案是网关层做鉴权，SqlRest 只在内网暴露，不直接对公网开放。数据库账号也要按最小权限分配：只读查询账号用SELECT权限就够了，不要给INSERT/UPDATE，防止 SQL 注入或误操作对数据造成不可逆影响。
监控方面，除开慢 SQL 日志，我更推荐在 pg 侧做兜底：pg_stat_activity 看会话，pg_stat_statements 看热 SQL，这是数据库层面最可靠的观测手段。SqlRest 应用侧能做的，是把日志格式里带上映射 ID 和参数摘要，这样慢 SQL 日志能直接定位到具体接口。
6.3 后续还能怎么扩展
跑通 1.6 版只是起点，SqlRest 这个框架后面值得深挖的方向不少。一是前端有低代码平台的需求时，SqlRest 完全可以作为底层数据接口服务，接口生成速度能跟上前端搭页面的速度。二是对接 BI 工具，很多 BI 工具支持自定义 SQL 数据源，但安全性不好控制；通过 SqlRest 把 BI 查询收敛到已审批的映射接口，既能保留灵活性，又能做审计。三是二次开发，框架源码并不复杂，你可以按需给它加接口分类、灰度发布、多租户隔离等能力。
我在实际项目中已经把 SqlRest 放在了服务层和数据层之间的位置，成了“数据查询网关”。前端不再直连数据库，所有查询都走映射接口；数据库账号收口到服务账号，权限控制、审计、限流都有了落点。这个架构在团队规模不大时非常高效，几个人维护一个数据服务就够了。如果你也在折腾数据服务化方向，不妨把这个 1.6 pg 版跑通，然后想想哪些查询可以收拢到 SqlRest 里，我猜你会发现业务拆解的思路都会变。
