企业官网建设流程全解析

做后端的人基本都遇到过这种需求：前端要一个列表、一个下拉框，或者一个报表数据。如果每次都写一套 Controller、Service、Mapper，小项目还好，接口一多就真的烦。今天要聊的 SqlRest 1.6，就是专门对付这种需求的——它把 SQL 直接映射成 REST 接口，数据库查询完直接通过 HTTP 返回，等于把"写接口"这件事简化成"写 SQL"。这篇文章记录的是我在 IDEA 里把 SqlRest 1.6 的 pg 版（PostgreSQL）完整跑起来的过程，从环境准备、项目导入、数据源配置到启动验证都有，最后还有我踩过的几个坑。不管你是想把 SqlRest 接进自己的项目，还是单纯想看看这个开源方案到底能不能用，都可以照着走一遍。

1. SqlRest到底是个什么东西

1.1 一句话理解它的核心机制

SqlRest 的核心思路，你可以理解成"把 SQL 文件当接口定义"。

传统方式里，要出一个"用户列表"接口，你得经历：建 Mapper、写 XML、写 Service、写 Controller、处理参数校验、包装返回结构……至少六个步骤。而 SqlRest 的做法是：你只需要在一个 SQL 文件里写好这条查询，给它起个名字，然后在 HTTP 请求里用这个名字去"调用"它。框架帮你完成参数解析、SQL 动态拼接、数据库查询、结果集序列化、分页处理，一条龙。

这种设计解决的实际问题非常明确：

• 接口开发周期大幅缩短，临时提数、报表查询、BI 看板这类场景尤其适合。
• 变更成本极低。SQL 改了，不用重新发布整个应用，因为接口只是 SQL 的一个映射。
• 对前端友好。前端只需要知道"接口名 + 参数"，不用关心 SQL 长什么样。
• 弱化后端编码门槛。很多纯 SQL 能解决的问题，不需要再靠 Java 代码绕一圈。

当然它不是万能的。它更适合"查询为主、逻辑简单、变更频繁"的数据服务场景。如果你的接口里有复杂的业务校验、事务、消息推送，那还是老老实实写业务代码。

1.2 为什么选择 pg 版

标题里特意标注了"pg 版"，说明这个版本是面向 PostgreSQL 的。很多开源项目默认演示用的是 MySQL，切到 pg 之后最大的几个差异点在这里：

pg 版在 SqlRest 里主要体现为：驱动选择、SQL 方言模板、以及一些类型映射上的适配。比如 pg 的 boolean 类型、jsonb 类型，和 MySQL 的 tinyint、json 返回出来的 Java 类型是不一样的，在结果序列化时要特别注意。

1.3 适合谁来读这篇

如果你属于下面任意一类，这篇文章可以直接照着操作：

• 想快速把 SqlRest 1.6 跑起来验证一下效果的人。
• 项目用的是 PostgreSQL，但网上教程大多是 MySQL，切过来总是报错的人。
• 对"SQL 即接口"这种轻量数据服务方案感兴趣，想看看它到底够不够用的人。

接下来按我的实际操作顺序，从零开始搭一遍。

2. 环境准备：一步都不能省

2.1 基础软件版本清单

我把整个环境列个表，直接用我这套组合基本不会出问题：

这里有个容易踩的坑：IDEA 自带的 Maven 和外部 Maven 混用。如果你本地已经装了 Maven，建议在 IDEA 的 Settings → Build Tools → Maven 里把 Maven home path 指到你自己的那个，同时确认 JDK 版本统一。版本不一致最典型的表现就是项目导入后依赖报错、编译级别不对。

2.2 检查 Java 和 Maven 环境

在终端里跑两条命令确认一下：

java -version mvn -version

Java 版本没问题后，确认 Maven 的 settings.xml 里有国内镜像。SqlRest 依赖的 Spring Boot 全家桶不算多，但第一次下载还是要花点时间，没有镜像的话有些包会非常慢。我直接在全局 settings.xml 里加了阿里云镜像：

<mirror> <id>aliyunmaven</id> <mirrorOf>*</mirrorOf> <name>阿里云公共仓库</name> <url>https://maven.aliyun.com/repository/public</url> </mirror>

这个步骤很多人忽略，等到 IDEA 导入项目时卡在下载依赖才回头补，纯浪费时间。

2.3 安装并初始化 PostgreSQL

PostgreSQL 安装完成后，第一件事是设置 postgres 用户的密码，并确认服务在监听 5432 端口。这一步没法跳过，因为后面 application.yml 里要写连接信息。

我习惯用命令行建库，比点界面快：

# 进入 psql 命令行 psql -U postgres # 创建测试库 CREATE DATABASE sqlrest_demo; # 建一个 schema（可选，默认用 public 就行） CREATE SCHEMA IF NOT EXISTS demo; # 切换库 \c sqlrest_demo

记两点：第一，pg 12+ 之后默认认证方式通常是 scram-sha-256，只要密码设置正确，从 Java 连接一般不会出问题；万一报认证失败，要检查 pg_hba.conf 里的规则。第二，一定要确认端口是 5432，如果本机装了多个 pg 实例，很容易连到旧实例上，后面排错会很头疼。

2.4 准备测试表数据

我用一个简单的用户表来验证。注意 pg 的建表语法，主键用 SERIAL，字符串用 varchar，时间字段用 timestamp：

CREATE TABLE t_user ( id SERIAL PRIMARY KEY, name VARCHAR(64) NOT NULL, age INT, email VARCHAR(128), status SMALLINT DEFAULT 1, create_time TIMESTAMP DEFAULT now() ); INSERT INTO t_user (name, age, email, status) VALUES ('张三', 25, 'zhangsan@demo.com', 1), ('李四', 30, 'lisi@demo.com', 1), ('王五', 22, 'wangwu@demo.com', 0);

插入几条数据后，用SELECT * FROM t_user;验证一下。如果这里查不出来，后面接口一定也查不出来。先确认底层数据没问题，再往上走。

3. 获取 SqlRest 1.6 源码并在 IDEA 中导入

3.1 从开源仓库拉取项目

SqlRest 项目一般托管在 Gitee / GitHub 上，直接搜索"SqlRest"或者找官方主页的仓库地址。这里不贴具体地址了，因为仓库链接可能会有变动。你自己搜的时候注意一点：版本号要选 1.6 的 tag 或分支，不要直接拉 master/main，那可能是新版本的开发分支，结构和配置项可能已经不一样了。

用命令行拉取后，切到 1.6 对应版本：

git clone <仓库地址> sqlrest-1.6 cd sqlrest-1.6 git tag # 查看有哪些 tag git checkout v1.6

如果没有合适的 tag，就选一个发布时间对应 1.6 的 commit。这一步很重要，SqlRest 后面的版本配置文件格式变过好几次，你照着 1.6 的教程去配新版，很容易对不上。

3.2 IDEA 导入 Maven 项目

IDEA 里导入 Maven 项目的标准动作：

1. 打开 IDEA，选 Open，找到刚才 clone 下来的目录，选择里面的 pom.xml。
2. 选择 "Open as Project"，IDEA 会自动识别为 Maven 项目。
3. 等待右下角的 Maven 依赖导入完成。第一次可能耗时几分钟，注意看状态栏进度条。

导入后，检查 Project Structure：

• File → Project Structure → Project → Project SDK，选你本地的 JDK 8 或 11。
• 检查 Language level，通常保持默认，如果报语法错误，设置为 8。
• Modules 里确认 SqlRest 的模块已经识别为 Maven 模块。

一个非常常见的问题是：IDEA 导入后出现一堆Cannot resolve symbol红色报错，多半是 Maven 依赖没有正确下载完。解决办法是：右侧 Maven 面板点刷新（Reload All Maven Projects），如果还不行，在终端执行mvn -U clean compile强制更新快照依赖。

3.3 项目结构快速认知

导入后，你不需要一下子看懂所有代码，但是下面几个关键位置要知道：

sqlrest-1.6 ├── pom.xml # 父工程，声明依赖版本 ├── sqlrest-core # 核心模块：SQL 解析、接口路由、执行引擎 ├── sqlrest-spring-boot-starter # 与 Spring Boot 集成的自动配置模块 ├── sqlrest-demo # 示例工程，通常包含启动类和配置文件 │ └── src/main/resources │ ├── application.yml # 核心配置 │ └── sqls/ # SQL 映射文件目录（有些版本叫 sqlrest） └── README.md

重点看 demo 模块，尤其是它的 application.yml，这就是我们要改的地方。有些版本把 demo 单独作为模块，IDEA 里右键 demo 模块的启动类直接运行即可，不需要运行整个父工程。

4. 核心配置：把 pg 数据源接进来

4.1 application.yml 数据源配置

这是整个启动过程中最容易出问题的地方。我直接给出一个可用的 pg 配置：

server: port: 8080 spring: datasource: driver-class-name: org.postgresql.Driver url: jdbc:postgresql://localhost:5432/sqlrest_demo username: postgres password: postgres hikari: maximum-pool-size: 10 minimum-idle: 2 sqlrest: enabled: true # SQL 映射文件所在目录，相对 classpath sql-file-path: sqls/ # 接口前缀，通过 /sql/xxx 访问 request-path-prefix: /sql # 是否打印 SQL 日志 show-sql: true

几个关键点：

• driver-class-name必须是org.postgresql.Driver，不是 MySQL 的驱动。这看起来像是废话，但很多人从 MySQL 迁移过来就是卡在这一行。
• URL 里sqlrest_demo是数据库名，要和你建库时完全一致。pg 的 URL 不需要加useSSL、serverTimezone这些 MySQL 参数，别把 MySQL 的习惯带过来。
• sql-file-path配置的是 SQL 文件的存放目录，这个路径是最容易配置错的，下面会单独讲。
• HikariCP 连接池参数按需调整。如果数据库和 Spring Boot 应用在同一台机器，maximum-pool-size设置为 10 就够用了，别上来就配 100，没必要，反而增加数据库的连接负担。

4.2 动态 SQL 文件应该怎么写

SqlRest 的 SQL 文件不是普通 SQL，它有自己的格式约定。以 1.6 为例，我用的格式是这样：

[query:userList] SELECT u.id, u.name, u.age, u.email, u.status FROM t_user u WHERE 1 = 1 [#if name] AND u.name LIKE CONCAT('%', #{name}, '%') [/if] ORDER BY u.id DESC [page:true]

大概的约定是：

• [query:接口名]声明这是一条查询 SQL，接口名就是请求路径里用的名字。
• [#if 参数]和[/if]是动态条件判断，等价于 MyBatis 里的<if test>。
• #{name}是参数占位符，最终会作为 PreparedStatement 的参数传入，可以防止 SQL 注入。
• [page:true]表示开启分页，框架会自动在 SQL 后面追加LIMIT ? OFFSET ?，这也是 pg 版必须要适配的地方。

pg 版本下，如果 SQL 里用了 MySQL 的习惯写法，会直接报语法错误。比如 MySQL 的LIMIT #{offset}, #{limit}、反引号包裹字段、IFNULL函数，在 pg 里分别对应LIMIT #{limit} OFFSET #{offset}、双引号包裹字段、COALESCE函数。

4.3 pg 版 SQL 写法的几个注意事项

如果你原来的接口业务是从 MySQL 迁过来的，建议把所有 SQL 先拿到 pgAdmin 里跑一遍，确认语法没问题再放到 SQL 文件里。SqlRest 只是把它拼接好的 SQL 发给数据库，SQL 本身有语法错误它帮不了你。

5. 启动、验证与 IDEA 调优

5.1 找到启动类并运行

在 demo 模块下找到带@SpringBootApplication注解的类，类名一般叫Application或SqlRestDemoApplication。右键类名选择 Run。

如果启动时提示没有 Main class，说明 IDEA 没有正确识别，检查一下：

• 启动类是否在 demo 模块的src/main/java下。
• Project Structure 里该模块有没有被标记为 Sources（蓝色）。

启动后控制台重点看这几个输出：

Tomcat started on port(s): 8080 (http) with context path '' Started Application in X.XXX seconds

看到这两句基本就成了。如果还有一层 SQL 文件加载的初始化日志，说明映射文件已经被扫描到。我说"基本"，是因为启动成功只代表应用起来了，SQL 映射有没有对还不一定，需要用实际请求来验证。

5.2 用 curl 验证接口

启动成功后，打开一个新的终端，跑一个请求：

curl "http://localhost:8080/sql/userList?name=%E5%BC%A0"

参数是 URL 编码后的 UTF-8 中文。返回的 JSON 大概是：

{ "code": 0, "message": "success", "data": { "total": 1, "list": [ { "id": 1, "name": "张三", "age": 25, "email": "zhangsan@demo.com", "status": 1 } ] } }

注意一个细节：分页接口返回的data里会有total和list两个字段，这和单条查询/非分页查询的结构不同。如果你对接前端，这个结构要事先跟对方说清楚，不然前端拿到数据会懵。

5.3 IDEA 中的启动参数与 Debug 技巧

在 IDEA 的 Run Configuration 里可以加 VM options，比如：

-Dserver.port=8081 -Dlogging.level.sqlrest=debug

server.port的意思是，如果你不想用默认端口，可以在不修改 yml 的情况下覆盖。logging.level.sqlrest=debug会把 SqlRest 内部打印的 SQL 日志打开，排查参数绑定时很有用。

想看 SQL 拼出来到底是什么样，直接在 IDEA 控制台里搜==> Preparing:或者项目自定义的 SQL 输出标识。如果发现 SQL 里参数变成了?，这是正常的，因为用了 PreparedStatement；要进一步看参数值，装一个 DBeaver，或者打开 pg 的log_statement = 'all'，不过这种姿势生产环境慎用，日志量太大了。

5.4 pg 版启动中的实际运行现象

我本地跑起来后有几个肉眼可见的区别，这里跟你交个底：

• 首次启动比 MySQL 版略慢，因为 HikariCP 连接 pg 时要多做一次握手，实际影响可以忽略。
• pg 的status字段如果定义成 smallint，返回给 Jackson 序列化后是 number，前端如果要布尔值，要么 SQL 里直接CAST(status AS BOOLEAN)，要么在应用层转换。这个不算 bug，但很多人会跟前端预期对不上。
• 如果 SQL 里写了LIMIT 10 OFFSET 0这种写死的分页，记得去掉，交给[page:true]处理。不然当参数变化时分页会错乱，排查起来会让人崩溃。

6. 常见问题与排查实录

6.1 启动时报数据库连接失败

这个错误几乎每个人都有过，我列几个典型的：

遇到Connection refused时，先别急着改配置，用 psql 命令行连接一下本地库：

psql -h localhost -p 5432 -U postgres -d sqlrest_demo

能连上，说明数据库没问题，问题出在 Java 这侧；连不上，先处理数据库服务或认证问题，再去调 yml。这个排查顺序能省掉大量无头苍蝇一样的时间。

6.2 SQL 文件加载失败、接口 404

启动没报错，但请求/sql/userList返回 404，这个问题九成出在sql-file-path配置上。

首先要明确：这个路径是相对于 classpath 的。如果配置文件在src/main/resources/application.yml，SQL 文件放在src/main/resources/sqls/，那sql-file-path就写sqls/。很多人喜欢把 SQL 文件放在项目根目录的某个文件夹，然后配置./sqls/或者绝对路径，1.6 版本不一定支持，直接结果就是 404。

检查方法很简单：编译之后看 target/classes 目录下面有没有 sqls/user.sql 这种结构。没有的话，说明资源没进 classpath，要么是构建配置没包含**/*.sql，要么目录位置放错了。

6.3 依赖下载失败或 IDEA 卡住

国内网络下 Maven 首次拉依赖是比较痛苦的。除了前面说的阿里云镜像，还有一个办法：如果你在别的地方跑过同一套项目，直接把本地仓库复制过来，避免重新下载。

IDEA 导入后一直卡在 Indexing 或 Resolving Dependencies 的状态，建议：

• 关闭 IDEA，删除项目目录里的.idea文件夹和根目录的target。
• 重新打开导入，让 IDEA 用 Maven 模型重新构建索引。

这两种方式基本能解决 90% 的"卡死"情况。注意一点：不要一边开着 IDEA 一边手动删 target，一定要先关闭软件再操作。

6.4 pg 特有的小坑汇总

最后把 pg 版特有的坑统一列一下，做成速查表：

7. 后续可以怎么扩展

SqlRest 跑通只是第一步，实际用到生产环境还有几个值得继续搞的方向。

一是多数据源路由。如果你的项目既有 pg 又有其他库，SqlRest 1.6 是否支持多数据源需要看版本，老版本一般只有配置里的单个spring.datasource。需要多个数据源的话，可以查查项目有没有dynamic-datasource的集成方案，或者自己封装一层数据源路由。

二是 SQL 文件的工程化管理。SQL 文件多了以后，命名规范、目录分模块、参数注释、权限控制都是要考虑的。不要让团队随随便便往一个目录里丢 SQL，接口名冲突会让你崩溃。建议从一开始就约定：一个业务模块一个目录，接口名跟业务名对齐，SQL 文件头部写清用途和参数说明。

三是监控和安全。SQL 接口直接暴露给前端是有风险的，生产环境至少要加一层鉴权，比如网关层校验 token、限制接口白名单。这个开源项目解决的是"接口生成效率"的问题，不解决"谁能访问"的问题，这个边界要拎清楚。

我个人在实际操作中最深的体会是：SqlRest 这种轮子，用好了是效率神器，用不好是隐患。它最让人舒服的一点是，改 SQL 不用重新走一遍发版流程；最让人担心的也是这一点，因为接口太容易加了，管理成本容易失控。如果你正在考虑要不要在团队里引入，建议先拿它搞定两个真实需求，再决定要不要铺开。

如果这篇文章帮你把 SqlRest 1.6 在 IDEA 里跑起来了，我建议你接下来去翻一下它的源码，重点看 SQL 文件解析那一块——你会发现它的设计思路其实非常轻巧，正因为轻巧，才有生命力。