真实落地时，大家会马上追问：谁能调这个接口？能看到哪些字段？一次上限查多少？慢查询谁负责？数据源密码放哪？字段改名会影响哪些接口？有没有审计记录？这些都不是 SQL2API 本身能顺手解决的问题。

这一篇聊背景：为什么要从一个 SQL2API 工具，继续往数据开放平台演进，以及平台的架构怎么拆。

一、从 SQL2API 到数据开放平台

SQL2API 解决的是一个很具体的问题：把 SQL 变成 API，省掉 CRUD 的模板代码。 这个能力很有价值，但它只是数据开放链路里的一个环节。

真实场景里，一个完整的数据开放链路长这样：

1. 数据接入：连各种数据源（MySQL、PostgreSQL、ES、Hive、API），把数据接进来
2. 数据加工：字段映射、格式转换、数据脱敏、聚合计算
3. 服务发布：把加工后的数据发布成 API，支持多种协议（REST、gRPC、WebSocket）
4. 访问控制：AK/SK 认证、租户隔离、流量控制、配额管理
5. 监控治理：调用链追踪、慢查询告警、数据血缘、审计日志
6. 运维管理：灰度发布、容灾备份、SDK 生成、文档管理

SQL2API 只覆盖了第 3 步的一部分。要从"工具"升级为"平台"，需要把这六步都串起来，而且要能长期运维。

类比一下：SQL2API 是一个厨师，能把食材做成菜。数据开放平台是一个餐厅，从采购（数据接入）、备菜（数据加工）、烹饪（服务发布）、上菜（访问控制）、品控（监控治理）到运营（运维管理），全流程都有。

1.1 为什么不直接开放数据库

有人会问：既然本质是查数据，为什么不直接给业务方一个只读账号，让他们连库查？

这个方案短期速度高，长期更麻烦：

• 权限太粗：数据库账号一般按库、表授权，很难细到"这个应用只能看订单表里的 5 个字段"。
• 审计断层：只能看到某个账号执行了 SQL，很难还原到具体应用、具体接口、具体业务场景。
• 流量不可控：一个全表扫描或者大分页，就可能把线上库拖慢。
• 数据口径失控：每个调用方自己写 SQL，同一个指标可能有三种算法。
• 变更风险大：表结构改了，谁受影响靠猜，没人愿意拍胸脯。

所以数据库可以作为底座，但不应该直接暴露给调用方。平台要把权限、限流、审计、口径和 SLA 都挡在前面。

1.2 为什么也不能只靠网关

API Gateway 很重要，但它解决的是入口问题：认证、限流、路由、协议转换。它不知道某个接口背后查了哪些表，也不知道手机号字段该不该脱敏，更不知道这个 SQL 是否会扫全表。

数据开放平台需要补的是数据侧能力：

• 权限：应用级、API 级、字段级、数据范围级权限。
• 审计：谁在什么时间，用什么参数，访问了什么数据。
• 限流与配额：保护平台，也保护底层数据库。
• 元数据：数据源、表、字段、接口、参数、返回结构都要可管理。
• 血缘：一个字段变更，要知道影响哪些 API 和调用方。
• 数据源管理：连接池、密钥、健康检查、备用数据源不能散落在代码里。
• SLA：接口超时、成功率、慢查询、告警都要有明确指标。

这些能力靠网关很难补齐，必须下沉到数据服务平台本身。

上一篇： 数据开放平台（一）：从 SQL2API 到数据开放平台的演进

SQL 转 API 引擎是整个数据开放平台的核心。用户在界面上写一条受控 SQL 模板，配好参数规则，系统自动生成一个可调用的 API。听起来简单，但要做到"运行时解析、校验、执行、审计"这一整套链路，细节其实不少。

下面看看这个引擎到底是怎么实现的。

一、为什么选 JdbcTemplate

结论：这个场景里，执行层放在 JdbcTemplate 上。

为什么不是 JPA？因为 JPA 要求编译期定义 Entity，SQL2API 的 SQL 在运行时才确定，核心不知道返回什么字段。JPA 的 EntityManager 也执行原生 SQL，但返回值绑死在 Entity 上，灵活性为零。

为什么不是 MyBatis？MyBatis 的 XML 是编译时写死的，要支持运行时动态 SQL 得 hack 进 Configuration 对象，线程不安全、内存泄漏、复杂度高。收益为零。

JdbcTemplate 的好处是足够薄：

// 运行时执行任意 SQL，返回 List<Map>
List<Map<String, Object>> result = jdbcTemplate.queryForList(
    "SELECT * FROM user WHERE status = ? AND name LIKE ?",
    status, "%" + name + "%"
);
// 结果直接是通用 Map，不用定义任何 Entity
// 连接自动归还，异常自动处理，参数自动绑定防注入

它不要求提前定义 Entity，也不强行接管 SQL 生成过程。对于"运行时执行 SQL 模板，返回通用结构"这个场景，JdbcTemplate 的抽象刚刚好：连接释放、异常转换、参数绑定这些脏活它来做，SQL 的控制权仍然在平台手里。

上一篇： 数据开放平台（二）：SQL 转 API 引擎

数据开放平台把数据变成 API 给外部调用，安全问题是第一位的。谁都能调不行，调了不该看的字段也不行，更不能让某个调用方把数据库连接池打满。

这一篇聊三个问题：怎么认证调用方身份、怎么隔离不同租户的数据、怎么控制调用频率。

一、AK/SK 签名认证

认证方案有很多种，为什么选 AK/SK？因为数据开放平台的调用方通常是服务端应用，不是浏览器用户。服务端对服务端的认证，AK/SK 是更成熟的方案，AWS、阿里云、腾讯云的开放 API 全用这个。

核心概念

• Access Key (AK)：调用方的身份标识，公开的，放在请求头里
• Secret Key (SK)：签名密钥，保密的，不在网络上传输
• 签名 (Signature)：用 SK 对请求内容做 HMAC-SHA256，服务端验签

为什么 SK 不直接传？因为网络传输可能被中间人截获。签名的好处是：即使签名被截获，攻击者也无法反推出 SK，而且签名是和请求内容绑定的，换个请求签名就失效了。

签名流程

AK/SK 认证的关键是两端对同一份规范化请求做签名，服务端不接收明文 SK：

调用方发起请求时：

上一篇： 数据开放平台（三）：鉴权与访问控制

SQL 查出来的原始数据，通常不能直接给调用方用。数据库字段名是 user_name，调用方要 userName；手机号 13812345678 不能直接暴露，得打成 138****5678；日期格式是 2026-04-23 10:30:00，调用方只要 2026-04-23。

这些"末尾一公里"的数据加工，就是数据转换引擎干的事。它不是替代数仓 ETL，也不应该把复杂计算都塞到接口层；它更适合做轻量、在线、和接口返回强相关的处理。

一、整体设计

数据转换引擎用规则驱动的架构。用户在界面上配置转换规则，运行时引擎按规则依次处理。每条规则是一个独立的 Handler，可插拔、可组合。

数据转换流水线要把字段形态写清楚，避免后续在响应层临时拼逻辑：

@Component
public class DataTransformEngine {

    // 所有 TransformHandler 按 Order 排序
    @Autowired
    private List<TransformHandler> handlers;

    public List<Map<String, Object>> transform(TransformConfig config,
                                                 List<Map<String, Object>> rawData) {
        if (config == null || config.isEmpty()) {
            return rawData;
        }

        List<Map<String, Object>> result = new ArrayList<>(rawData);
        for (TransformHandler handler : handlers) {
            if (handler.supports(config)) {
                result = handler.apply(config, result);
            }
        }
        return result;
    }
}

生产里我会给转换引擎加两个边界：第一，单次处理行数不能无限大，超过阈值必须分页或异步导出；第二，规则执行要记录耗时，某条自定义正则特别慢时能快速定位。

上一篇： 数据开放平台（四）：数据转换与加工

数据开放平台上线之后，更怕两件事：一是出了问题不知道，二是知道了问题找不到原因。API 响应慢了，是 SQL 没走索引还是数据库负载高？某个调用方报错，是参数传错了还是数据源挂了？某个字段被改了，谁改的？什么时候改的？

这些问题靠翻代码加日志是搞不定的，需要系统化的监控和治理能力。这一篇聊四个核心能力：调用链追踪、慢查询告警、数据血缘、审计日志。

一、调用链追踪

每个 API 调用都要记录完整的执行链路：从请求进来到响应返回，中间经历了哪些步骤，每步耗时多少。

TraceId 机制

每个请求分配一个全局唯一的 TraceId，贯穿整个调用链。后续所有日志、指标、告警都带上这个 TraceId，方便关联查询。

@Component
@Order(-100) // 最先执行
public class TraceHandler implements PipelineHandler {

    private static final String TRACE_ID = "X-Trace-Id";

    @Override
    public void before(SqlApiConfig config, Map<String, Object> params,
                        PipelineContext context) {
        // 优先用调用方传来的 TraceId（链路透传）
        String traceId = RequestContext.getHeader(TRACE_ID);
        if (traceId == null) {
            traceId = generateTraceId();
        }
        context.setTraceId(traceId);

        // 记录请求开始时间
        context.setStartTime(System.currentTimeMillis());

        // TraceId 放入 MDC，后续日志自动带上
        MDC.put("traceId", traceId);
        MDC.put("apiId", config.getApiId());
        MDC.put("apiPath", config.getApiPath());
    }

    @Override
    public void after(SqlApiConfig config, Object result,
                       PipelineContext context) {
        long elapsed = System.currentTimeMillis() - context.getStartTime();
        log.info("API 调用完成 traceId={} api={} elapsed={}ms rows={}",
            context.getTraceId(), config.getApiPath(), elapsed,
            result instanceof Collection ? ((Collection<?>) result).size() : 1);
        MDC.clear();
    }

    private String generateTraceId() {
        return UUID.randomUUID().toString().replace("-", "").substring(0, 16);
    }
}

调用链记录

每个步骤的耗时和结果都记录下来，形成完整的调用链：

上一篇： 数据开放平台（五）：监控与治理

前面五篇聊了架构、引擎、鉴权、转换、监控，都是"怎么设计"。这一篇聊"怎么落地"，接入流程怎么走、SDK 和文档怎么生成、上线怎么灰度、出了问题怎么兜底。

我自己的经验是，数据开放平台成不成，末尾不只看代码写得多漂亮，更看流程有没有闭环：申请、审批、联调、发布、监控、回滚、下线，每一步都要有人负责、有记录可查。

一、接入流程

一个新调用方从注册到正式使用，标准流程分四步：

接入流程要把审批、联调、发布、观察放进同一条链路，避免接口上线后没人认领：

第一步：申请接入

调用方在管理后台提交接入申请，填写：应用名称、负责人、使用场景、预期 QPS、需要访问的数据范围。审批通过后，系统自动生成 AK/SK 并分配配额。

@Service
public class AppRegistrationService {

    @Transactional
    public AppInfo register(AppRegistrationRequest request) {
        // 1. 生成 AK/SK
        String accessKey = "ak_" + UUID.randomUUID().toString().replace("-", "");
        String secretKey = "sk_" + UUID.randomUUID().toString().replace("-", "");

        // 2. 保存应用信息
        AppInfo app = AppInfo.builder()
            .appName(request.getAppName())
            .accessKey(accessKey)
            .secretKey(encrypt(secretKey)) // SK 加密存储
            .owner(request.getOwner())
            .status(AppStatus.PENDING)
            .dailyQuota(request.getDailyQuota() != null ?
                request.getDailyQuota() : 10000)
            .qpsLimit(request.getQpsLimit() != null ?
                request.getQpsLimit() : 100)
            .build();
        appMapper.insert(app);

        // 3. 发送审批通知
        notifyAdmin("新接入申请: " + request.getAppName(), app);

        return app;
    }
}

SK 只在创建时展示一次，后续后台只能重置不能查看。这个规则一定要写进产品交互里，否则密钥加密存储就只做了一半。