第一章 场景——数据就在那儿，但用不了

周二上午十点，运营部门的小王在企业微信上发来一条消息："张工，我们这周要做客户复购率分析，需要客户订单表、商品信息表和会员积分表，字段清单我发你。"附件里列了三十多个字段，横跨CRM（Customer Relationship Management，客户关系管理）系统、ERP（Enterprise Resource Planning，企业资源计划）系统和营销活动平台三个独立数据库。

张工看了一眼消息，心里默默列了一下工作清单：先确认这三个系统的数据库只读账号还在不在、分别登录查询表结构和字段名是否匹配、找开发排期写一个RESTful API服务把数据整合出来、配一套鉴权机制防止未授权访问、再写一份接口文档给小王对接——这套流程走下来，保守估计两天。而小王那边，复购率分析的报告周五就要交。

这个场景在多数企业的IT部门几乎每天都在上演。数据治理的前几步——梳理数据资源、采集汇聚、建仓存储、质量管控——都在推进，但到了最后"用出去"这一步，往往卡在了一个手工开发的瓶颈上。让业务部门直接连数据库是不现实的（安全风险和权限管控都不可控），把数据导出成Excel文件传递又丧失了实时性和可追溯性，而走正规的API开发流程，开发和测试周期又太长。

API（Application Programming Interface，应用程序编程接口）是当下最灵活的跨系统数据共享方式，因为调用方不需要知道底层数据库的结构，只需要按约定好的请求格式发送一个HTTP请求就能获取数据，数据库账号密码完全不暴露。但手工开发API意味着每个数据共享需求都要经历"需求评审→代码开发→安全审计→接口文档→联调测试"的完整软件工程流程，效率低、安全控制靠人工保障容易遗漏。

龙石数据中台的数据共享模块在设计上正是针对这一瓶颈。它对应"理、采、存、管、用"五阶方法论中"用（促共享重应用）"阶段的核心能力——选择数据源后通过可视化界面编写SQL（Structured Query Language，结构化查询语言）生成API，再通过鉴权（Authentication，身份验证）、IP白名单（IP Allowlist，来源限制）、流量控制（Rate Limiting，调用量限制）三道防线保障访问安全，整个配置过程不需要写一行代码。

---

第二章 前置条件——API发布前要准备好什么

一、共享库数据源已接入

确认数据源接入中，共享库的数据源已配置并连接正常。数据中台采用五层分层架构：来源库（SRC，Source）直接从业务系统接入原始数据；贴源库（ODS，Operational Data Store）保存镜像数据；治理库（DW，Data Warehouse）完成清洗和标准化；应用库（ADS，Application Data Store）存放面向业务场景的汇总数据；共享库（DS，Data Sharing）是数据中台对外提供数据共享服务的统一出口。

自助API默认从共享库DS层读取数据对外提供服务，因为DS层的数据已经过了完整的数据质量校验和标准化处理。但不仅限于DS层——也可选择DW层或ADS层作为数据源。检查路径为「数据集成→数据源接入」，确认连接状态为"正常"。

二、了解目标数据表结构

明确要共享的表名、字段清单，以及哪些字段需要脱敏处理（Data Masking，如身份证号、手机号、银行卡号等）。自助API支持主子表嵌套返回，同时提供字段转换规则引擎，支持值映射（Value Mapping）、日期格式化、正则表达式、默认值填充以及字符串脱敏等多种后处理能力。提前梳理好敏感字段清单，可以在API配置过程中一次性完成。

前置条件	确认位置	说明
共享库数据源已接入	数据集成→数据源接入	连接状态正常
了解表结构和敏感字段	数据治理→元数据管理	明确哪些字段需脱敏

---

第三章 操作步骤——创建API服务与自助API

3.1 创建API服务

第一步是创建一个API服务。API服务是多个API的逻辑分组容器——同一个业务域下的多个API（如客户域下的客户信息查询、订单查询、积分查询等）统一归属到一个API服务下管理。进入「数据共享→API共享→服务维护」，点击"新增服务"。

服务名称（英文，如customer）会作为API访问地址的前缀——假设数据中台部署在http://192.168.1.100:8080，服务名称为customer，则该服务下所有API的访问地址都以http://192.168.1.100:8080/customer/开头。服务名称要求全平台唯一，建议按业务域命名，字母开头、长度控制在32位以内。

创建服务的同时即可配置流控管理，这是访问控制的第一道防线。流控包含两个核心指标：并发数（同一时刻系统正在处理的请求数量上限，数值范围1-9999）和日最大访问量（一天内系统处理的总请求数上限，数值范围1-9999）。配置完成后点击"上线"按钮使服务生效。

配置项	填写内容	说明
服务名称	英文，如customer	作为API地址前缀，字母开头，1-32位
服务显示名称	中文，如"客户数据服务"	管理界面识别用
并发数	1-9999	服务级并发数上限
日最大访问量	1-9999	服务级日调用总量上限

3.2 新增自助API

进入「数据共享→API共享→API管理」，点击"新增自助API"。自助API（Self-Service API）是通过自定义SQL语句直接从数据库查询数据并返回结果的API，属于零代码开发模式——配置者只需编写SQL和设置基本参数，平台自动生成完整的RESTful接口。

自助API采用六步引导式配置流程：

第一步：设置API基本信息

配置项	说明
API名称	中文，如"客户订单查询接口"
请求方法	GET（查询类）/ POST（提交数据或复杂查询）
鉴权模式	签名模式（HMAC-SHA1动态签名）/ 简易模式（仅校验AppKey）/ 不鉴权
API路径	URL访问路径，全平台唯一，如/customer/order/query

第二步：配置查询SQL语句

选择数据源（推荐DS层），编写SQL。SQL中使用${参数名}占位符引用查询参数——当调用方发起API请求时，URL中传递的参数值会自动填入SQL占位符位置。例如SQL写为SELECT * FROM customer_order WHERE customer_id = ${customerId}，调用方请求/customer/order/query?customerId=12345时，实际执行的SQL会替换为SELECT * FROM customer_order WHERE customer_id = '12345'。

自助API支持主子表嵌套返回的高级特性。主表设置数据集标识（如student），子表引用主表标识作为前缀（如${student.no}），平台自动组织嵌套JSON结构。

第三步：转换规则设置

对敏感字段或需要格式化的字段添加转换规则。平台内置的规则类型包括值映射、日期格式化、字符串脱敏等。脱敏（Data Masking）是共享场景下使用频率最高的转换规则——以身份证号脱敏为例：设置开始位置4、结束位置14、替换内容*，则原始值320102199001011234输出为320**********1234。

第四步：测试API

填写测试值，点击测试，验证SQL逻辑、参数映射和转换规则。

第五步：流量控制

为该API单独设置并发数和日最大访问量。API级流控优先级高于服务级流控。建议对核心业务API单独设置更严格的阈值。

第六步：下载API文档

平台自动生成完整API文档，包括请求方法、请求类型、鉴权模式、输入/返回参数清单和返回示例。调用方无需人工沟通即可完成对接。

3.3 了解其他API类型

穿透API（Proxy API）：将已有的第三方API注册到数据中台统一纳管，平台作为代理层实现地址转换、统一鉴权、调用日志。

编排API（Orchestration API）：通过拖拽式可视化画布组装复杂的API流程。组件库包括Restful API调用、WebService调用、数据库表查询/输出/更新、JSON/XML报文互转、条件判断、流程分支等。编排API适用于跨系统数据聚合和跨多库事务性操作。

---

第四章 操作步骤——配置访问控制策略

访问控制是API共享安全的基石。龙石数据中台提供三道防线构成纵深防护体系：鉴权（验证调用者身份——“你是谁”）→ IP白名单/黑名单（控制访问来源——“从哪来”）→ 流量控制（限制调用频次——“用多少”）。

4.1 第一道防线：API鉴权

进入「数据共享→API共享→API授权」，平台采用统一的AppKey + SecretKey（应用密钥对）授权模式。三种鉴权模式：

鉴权模式	技术原理	适用场景	安全等级
签名模式	HMAC-SHA1对请求参数动态生成签名，每次签名不同，可防重放攻击	交易数据、个人信息、财务数据	★★★
简易模式	仅校验AppKey是否有效，不校验参数是否被篡改	内部系统间非敏感数据查询	★★☆
不鉴权	不采取身份验证措施	公开数据、测试环境	★☆☆

配置建议：涉及个人信息的API必须用签名模式；内部非敏感数据可用简易模式；测试阶段临时不鉴权需同时开启白名单限制。

4.2 第二道防线：IP白名单/黑名单

进入「数据共享→API共享→白名单 / 黑名单」。白名单（Allowlist）开启后仅允许列表内IP发起请求，遵循最小权限原则。黑名单（Blocklist）将非法或异常IP加入后直接拒绝请求。推荐"白名单为主、黑名单为辅"的组合策略。

配置白名单时注意：如果API前有负载均衡器或API网关，务必把网关的出口IP也加入白名单。

4.3 第三道防线：流量控制

流量控制从调用频次维度保护后端服务稳定性：

层级	控制指标	配置位置
服务级流控	并发数 + 日最大访问量	API服务维护
API级流控	并发数 + 日最大访问量	新增/编辑API

并发数防"洪峰型"攻击——瞬间大量并发请求。日最大访问量防"渗透型"消耗——持续低频但高总量的异常调用。两项指标缺一不可，生产环境务必两项都设置。

---

第五章 验证结果——发布后的监控与调用

API发布上线后，可通过平台内置测试功能、Postman或cURL三种方式调用验证。重点检查：返回字段完整性、数据准确性、脱敏效果。

进入「数据共享→API共享」，三个维度可视化监控：

分析维度	展示内容
服务维度	每日调用量（成功/失败）、历史总量、趋势图
用户维度	每个AppKey调用者的调用量和趋势——识别异常增长
API维度	每个API的调用量和趋势——定位热点接口

平台还提供"API集监控"功能，配置可用性监测（检查状态码200）、正确性监测（检查响应报文关键内容）、响应时间监测（检测是否超阈值）。任一项触发异常自动通过微信/短信/邮件告警。

---

第六章 配置速查模板

配置维度	配置项	填写内容	说明
服务维护	服务名称	英文，如customer	作为API地址前缀
	并发数	1-9999	服务级并发上限
	日最大访问量	1-9999	服务级日调用上限
自助API	请求方法	GET / POST	查询用GET，提交用POST
	鉴权模式	签名/简易/不鉴权	敏感数据用签名
	数据源	共享库DS/治理库DW/应用库ADS	推荐DS层
	SQL语句	SELECT ... WHERE field = ${param}	支持占位符绑定参数
转换规则	脱敏	位置+替换内容	身份证：位置4-14，替换*
	值映射	原始值→目标值	F→女、M→男
访问控制	白名单	IP地址列表	仅允许白名单IP访问
	黑名单	IP地址列表	拒绝黑名单IP访问

---

第七章 避坑指南与方法论收尾

避坑指南

坑一：测试时选"不鉴权"，上线后忘记切回签名模式。 测试阶段为了调试顺畅选了不鉴权，上线检查清单漏了鉴权确认——API在公网没有任何身份验证。正确做法：测试环境用"简易模式+白名单限制测试IP"组合，避免裸奔。

坑二：流控只配了并发数，没配日最大访问量。 并发数挡洪峰，日最大访问量挡渗透。Bug脚本每秒1次请求，并发数永远不会触发，但24小时就是86400次调用。两项缺一不可。

坑三：白名单配了业务服务器IP，漏了API网关IP。 API通过网关对外暴露时，到达数据中台的TCP连接源IP是网关IP而非业务服务器IP。配置白名单时需列出调用链上所有中间节点的出口IP。

从"开发两天"到"配置十分钟"

回到开头场景。没有数据中台之前，每次对外共享一个数据接口需要"确认数据源→排期→写Controller/Service/DAO代码→配鉴权→写文档→联调测试→部署上线"，最快两天。借助龙石数据中台的数据共享模块，流程简化为"进入资产目录→找到目标表→新建自助API→编写SQL→选择鉴权模式→开启白名单→设置流控→测试发布"，八个步骤全程在可视化界面完成，十分钟以内。后续的调用量统计、调用方管理、质量监控、异常告警全部由平台自动运转。

方法论收尾

龙石数据中台遵循"理、采、存、管、用"五阶方法论。API共享模块是"用"阶段的核心能力载体——它不是简单地"把数据扔出去"，而是在"服务维护→鉴权授权→黑白名单→双层流控→多维调用分析→持续质量监控"的完整机制框架下，实现数据在"用得出去"和"管得住"之间取得平衡。

在江苏某数据局的共享交换平台中，全市百余个政务节点、近4万个交换任务、千余个API服务稳定运行；在某211大学智慧校园项目中，跨部门数据申请从"天/周级"线下审批缩短到"分钟级"在线自助获取。

数据共享的价值不在于技术有多复杂，而在于访问有多简单、管控有多精细。

---

FAQ

1. 三种鉴权模式怎么选？

签名模式基于HMAC-SHA1动态签名防重放攻击，适用于交易数据、财务数据、个人信息。简易模式仅校验AppKey，适用于内部非敏感数据。不鉴权需同时开启白名单保护。

2. 白名单和鉴权能同时开启吗？

可以，两者是互补的安全维度。同时开启时，请求须同时满足AppKey合法和来源IP在白名单内。

3. 并发数和日最大访问量分别控制什么？

并发数控制同一时刻请求数上限（防洪峰），日最大访问量控制全天总请求数上限（防渗透）。不填写代表无限制，生产环境建议两项均设置合理阈值。

4. 自助API和穿透API有什么区别？

自助API是通过SQL从数据库直接查询生成全新API（零代码新建）。穿透API是将已有第三方API注册到平台统一纳管（不改原逻辑）。

5. API服务下线后能恢复吗？

服务下线后该服务下所有API立即停止响应。再次点击"上线"恢复——不会丢失配置信息，不影响AppKey/SecretKey授权关系，不清理调用统计。