周二上午十点，运营部门的小王在企业微信上发来一条消息："张工，我们这周要做客户复购率分析，需要客户订单表、商品信息表和会员积分表，字段清单我发你。"附件里列了三十多个字段，横跨CRM（客户关系管理）系统、ERP（企业资源计划）系统和营销活动平台三个独立数据库。张工看了一眼消息，心里默默列了一下工作清单：先确认这三个系统的数据库只读账号还在不在、分别登录查询表结构和字段名是否匹配、找开发排期写一个RESTful API（表述性状态传递接口）服务把数据整合出来、配一套鉴权机制防止未授权访问、再写一份接口文档给小王对接——这套流程走下来，保守估计两天。而小王那边，复购率分析的报告周五就要交。
这个场景在多数企业的IT部门几乎每天都在上演。数据治理的前几步——梳理数据资源、采集汇聚、建仓存储、质量管控——都在推进，但到了最后"用出去"这一步，往往卡在了一个手工开发的瓶颈上。让业务部门直接连数据库是不现实的（安全风险和权限管控都不可控），把数据导出成Excel文件传递又丧失了实时性和可追溯性，而走正规的API开发流程，开发和测试周期又太长。API（应用程序编程接口，Application Programming Interface）是当下最灵活的跨系统数据共享方式，因为调用方不需要知道底层数据库的结构，只需要按约定好的请求格式发送一个HTTP请求就能获取数据，数据库账号密码完全不暴露。但手工开发API意味着每个数据共享需求都要经历"需求评审→代码开发→安全审计→接口文档→联调测试"的完整软件工程流程，效率低、安全控制靠人工保障容易遗漏。
龙石数据中台的数据共享模块在设计上正是针对这一瓶颈。它对应"理、采、存、管、用"五阶方法论中"用（促共享重应用）"阶段的核心能力——选择数据源后通过可视化界面编写SQL（结构化查询语言，Structured Query Language，一种用于管理和查询关系型数据库的标准编程语言）生成API，再通过鉴权（身份验证，验证调用者是否具备合法的访问凭证）、IP白名单（来源限制，仅允许指定IP地址的请求通过）、流量控制（调用量限制，约束同一时间的并发数和单日的总调用次数）三道防线保障访问安全，整个配置过程不需要写一行代码。
第二章 前置条件——API发布前要准备好什么
在开始一键发布API之前，需要完成以下两个前置准备，确保配置过程顺畅无阻。
一、共享库（DS层）数据源已接入
确认数据源接入中，共享库的数据源已配置并连接正常。数据中台采用五层分层架构对数据进行递进式治理：来源库（SRC，Source）直接从业务系统接入原始数据；贴源库（ODS，Operational Data Store）保存与源系统结构一致的镜像数据；治理库（DW，Data Warehouse）完成数据清洗、标准化和模型设计；应用库（ADS，Application Data Store）存放面向具体业务场景的汇总结果数据；共享库（DS，Data Sharing）是数据中台对外提供数据共享服务的统一出口。自助API默认从共享库DS层读取数据对外提供服务，因为DS层的数据已经过了完整的数据质量校验和标准化处理，是数据治理后的"成品"数据。但不仅限于DS层——根据实际业务需要，也可以选择治理库DW层（需要标准化但无需对外统一出口的数据）或应用库ADS层（面向具体业务场景的汇总数据）作为API的数据源。检查路径为「数据集成→数据源接入」，确认所需数据源的连接状态为"正常"。
二、了解目标数据表结构
明确要共享的表名、字段清单，以及哪些字段需要脱敏处理（如身份证号、手机号、银行卡号等个人敏感信息）。自助API在配置SQL时支持主子表嵌套返回——主查询返回主表数据，子查询返回关联的子表数据，最终以嵌套JSON结构输出。同时平台提供字段转换规则引擎，支持值映射（如将代码值"F"转换为"女"）、日期格式化、正则表达式、默认值填充以及字符串脱敏等多种后处理能力。提前梳理好敏感字段清单，可以在后续第三步"转换规则设置"中一次性完成配置，避免API上线后发现数据脱敏遗漏再回退修改。
关键配置前置条件速查
| 前置条件 | 确认位置 | 说明 |
|---|---|---|
| 共享库数据源已接入 | 数据集成→数据源接入 | 共享库DS数据源连接正常 |
| 了解表结构和敏感字段 | 数据治理→元数据管理 | 明确哪些字段需脱敏处理 |
第三章 操作步骤一——创建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，不填写则无限制）。这两个指标分别从"瞬间冲击"和"持续消耗"两个维度保护后端数据库。配置完成后点击"上线"按钮使服务生效——注意，创建服务不等于服务上线，服务上线后该服务下的API才可被调用；服务下线后该服务下所有API均不可调用，再次上线后立即恢复（配置和授权关系均不会丢失）。
API服务维护配置表
| 配置项 | 填写内容 | 说明 |
|---|---|---|
| 服务名称 | 英文，如customer |
作为API访问地址前缀，字母开头，长度1-32位 |
| 服务显示名称 | 中文，如"客户数据服务" | 管理界面识别用，调用方不可见 |
| 并发数 | 1-9999（不填视为无限制） | 服务级并发数上限，控制同一时刻的并发请求量 |
| 日最大访问量 | 1-9999（不填视为无限制） | 服务级日调用总量上限，控制单日总请求数 |
3.2 新增自助API
创建好API服务后，下一步是新建具体的API。进入「数据共享→API共享→API管理」，点击"新增自助API"。自助API（Self-Service API）是通过自定义SQL语句直接从数据库查询数据并返回结果的API，属于零代码开发模式——配置者只需编写SQL和设置基本参数，平台自动生成完整的RESTful接口，省去了传统开发中"写Controller→写Service→写DAO→写测试用例"的全部编码工作。目前平台支持的数据库类型包括MySQL、Oracle、SQLServer、PostgreSQL、DM8（达梦数据库）、Doris（Apache Doris分析型数据库）以及Vastbase_G100（海量数据库）等主流数据库。
自助API采用六步引导式配置流程，下面逐一说明。
第一步：设置API基本信息
| 配置项 | 填写说明 |
|---|---|
| API名称 | 自定义API名称（中文），如"客户订单查询接口"，便于管理识别 |
| 请求方法 | GET（查询类接口）/ POST（提交数据或复杂查询场景） |
| 请求类型 | GET方法无需设置；POST方法可选application/json等格式 |
| 鉴权模式 | 签名模式（HMAC-SHA1动态签名）/ 简易模式（仅校验AppKey）/ 不鉴权（详见第四章） |
| API路径 | URL访问路径，全平台唯一，如/customer/order/query |
| API描述 | API用途说明，便于调用方理解接口功能 |
第二步：配置查询SQL语句
选择数据源（推荐选择已接入的共享库DS层数据源，也可根据业务需要选择治理库DW层或应用库ADS层，检查路径：「数据集成→数据源接入」），然后编写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'。编写完SQL后点击"执行SQL"按钮，系统会自动识别SQL中的参数占位符并展示在"输入参数"和"返回参数"区域中，参数的类型和示例值由系统根据数据库元数据自动推断。
自助API支持主子表嵌套返回的高级特性。主表查询和子表查询通过"数据集标识"进行关联：主表设置一个英文标识（如student），子表在查询参数中引用主表的数据集标识作为前缀（如${student.no}），平台会自动按关联键组织嵌套JSON结构。以学生信息系统为例，主表student_info查询学生基本信息，数据集标识设为student，SQL为select * from student_info where no = ${no}；子表student_profiles查询学生各科成绩，数据集标识设为score，SQL为select * from student_profiles where no = ${student.no}——返回结果会以如下嵌套JSON结构呈现：
{
"student": {
"no": "2024001",
"name": "张三",
"class": "计算机科学2024级"
},
"score": [
{"no": "2024001", "subject": "数据结构", "score": 92},
{"no": "2024001", "subject": "操作系统", "score": 88}
]
}
第三步：转换规则设置
在返回参数列表中，对敏感字段或需要格式化的字段点击"添加规则"按钮。平台内置的转换规则类型包括：值映射（将代码值转换为可读中文，如性别字段F→女、M→男）、剪切字符串、日期格式化（如将时间戳1700000000转换为2023-11-15）、正则表达式提取、默认值填充（当字段值为空时自动填入默认值）、字符串补齐、字符串脱敏以及自定义脚本等。
脱敏（Data Masking，数据遮蔽）是共享场景下使用频率最高的转换规则。以身份证号脱敏为例：选择"字符串脱敏"规则，设置开始位置为4、结束位置为14、替换内容为*，则原始值320102199001011234经规则处理后输出为320**********1234——出生日期信息被遮蔽，但仍保留了地区码和校验位供必要时进行区域统计或格式校验。
第四步：测试API
填写输入参数的测试值，点击测试按钮，系统将在右侧展示完整的请求URL、响应状态码和返回数据结果。测试环节需要重点验证三个方面：SQL逻辑是否正确（返回的数据是否符合预期筛选条件）、参数映射是否准确（入参值是否被正确替换到SQL中）、转换规则是否生效（脱敏字段和格式化字段输出是否符合规则设定）。
第五步：流量控制
为该API单独设置并发数和日最大访问量。API级流控的优先级高于服务级流控——当API级流控设置了独立阈值时，该API以API级阈值为准，不受服务级阈值约束；当API级未设置时，继承服务级流控配置。建议对核心业务API（如订单查询、支付状态查询）单独设置更严格的API级流控，保证关键业务的资源独占；对辅助性API（如字典查询、配置查询）可以复用服务级的默认流控阈值。不填写代表无限制，生产环境建议两项均设置合理阈值。
第六步：下载API文档
配置完成后，平台自动生成一份完整的API接口文档，内容包括请求方法（GET/POST）、请求类型（Content-Type）、鉴权模式、输入参数清单（参数名、类型、是否必填、示例值）、返回参数清单（字段名、类型、说明）、返回示例（JSON格式的样例数据）。调用方无需人工沟通，参考文档即可完成对接开发，大幅降低跨团队的沟通成本。
自助API六步配置速查
| 步骤 | 操作 | 关键配置 | 说明 |
|---|---|---|---|
| 第一步 | API基本信息 | API名称、请求方法、鉴权模式 | GET用于查询，POST用于提交或复杂查询 |
| 第二步 | 查询SQL | 数据源、SQL语句、数据集标识 | 支持${}参数占位符和主子表嵌套 |
| 第三步 | 转换规则 | 脱敏、值映射、日期格式化 | 对敏感字段和格式化字段添加规则 |
| 第四步 | 测试API | 测试参数值 | 验证SQL逻辑、参数映射、转换规则 |
| 第五步 | 流量控制 | 并发数、日最大访问量 | API级流控优先级高于服务级 |
| 第六步 | 下载文档 | 自动生成 | 含请求/返回参数和样例数据 |
3.3 了解其他API类型（背景补充）
除了自助API之外，龙石数据中台还提供了两种辅助型API类型，用于覆盖"已有API纳管"和"复杂流程编排"两类场景。
穿透API（Proxy API）：企业往往已经有一些现成的第三方API在运行，这些API分散在不同的系统中，管理起来很不方便。穿透API的作用是把已有的第三方API注册到数据中台统一纳管——不需要修改原API的任何代码逻辑，平台作为代理层实现地址转换（调用方访问平台统一地址，平台透明转发到真实API地址）、统一鉴权（在平台层叠加鉴权策略）、调用日志（自动记录每次调用的请求和响应详情）。新增穿透API时，请求方法、请求类型、鉴权模式、代理地址等参数必须与原API完全一致，否则代理转发会失败。
编排API（Orchestration API）：当单个自助API无法满足需求时——比如需要一次请求同时调用多个数据源的接口并融合返回结果，或者需要按条件分支执行不同的API调用链——编排API提供了拖拽式可视化画布来组装复杂的API流程。编排组件库包括：Restful API调用、WebService（一种基于SOAP协议的网络服务接口标准）调用、数据库表查询/输出/更新、JSON/XML报文互转、条件判断、流程分支以及Java自定义逻辑等。编排API适用于跨系统数据聚合、主子表跨多库的事务性保存、跨系统业务流程触发等复杂场景。举例来说，一个"创建订单"的编排API可以在一次请求中同时完成在订单库插入订单记录、在库存库扣减库存、在用户库检查并更新用户等级——三个数据库操作要么全部成功、要么全部回滚，保证数据一致性。
第四章 操作步骤二——配置访问控制策略
访问控制是API共享安全的基石。龙石数据中台提供三道防线构成纵深防护体系：鉴权（验证调用者身份——"你是谁"）→ IP白名单/黑名单（控制访问来源——"从哪来"）→ 流量控制（限制调用频次——"用多少"）。三道防线既可以独立使用也可以灵活组合，适配从公开数据到敏感交易数据的不同安全等级需求。
4.1 第一道防线：API鉴权——验证"你是谁"
鉴权（Authentication，身份认证）回答的是"谁在调用这个API"的问题。进入「数据共享→API共享→API授权」，平台采用统一的AppKey + SecretKey（应用密钥对）授权模式：系统为每个调用者自动生成一对唯一的AppKey（应用标识）和配对的SecretKey（应用密钥），AppKey作为调用者的身份标识在API请求中传递，SecretKey由调用方妥善保管用于生成请求签名，不通过网络传输。
平台提供三种鉴权模式，在新增或编辑API时选择：
| 鉴权模式 | 技术原理 | 适用场景 | 安全等级 |
|---|---|---|---|
| 签名模式 | 使用HMAC-SHA1（基于哈希的消息认证码算法，Hash-based Message Authentication Code with SHA-1）对请求参数动态生成签名摘要。每次请求的签名都不同（因为包含了时间戳和随机数），可有效防止重放攻击——攻击者截获一个请求后无法直接重复使用，因为过期的签名会被服务端拒绝 | 交易数据、个人敏感信息（如身份证号、手机号、银行卡号）、财务数据等 | ★★★ |
| 简易模式 | 仅校验请求中携带的AppKey是否在平台中存在且处于有效状态，不校验请求参数是否被篡改 | 内部系统之间的非敏感数据查询、低频调用场景 | ★★☆ |
| 不鉴权 | 不采取任何身份验证措施，任何人知道API的完整URL地址即可发起调用 | 公开数据（如天气、节假日信息）、测试环境调试阶段 | ★☆☆ |
配置建议：涉及用户个人信息的API必须使用签名模式；内部系统间的非敏感数据查询（如部门列表、组织架构）可使用简易模式降低对接复杂度；测试阶段的API可临时选择不鉴权，但务必同时开启白名单将访问来源限定在测试服务器的IP范围。API上线后可以随时修改鉴权模式——服务下线→修改鉴权模式→重新上线即可生效，已有的授权关系不丢失。
4.2 第二道防线：IP白名单/黑名单——控制"从哪来"
进入「数据共享→API共享→白名单 / 黑名单」。白名单和黑名单从网络层面对调用来源进行准入控制，是鉴权的有效补充——鉴权回答"你是谁"，白名单/黑名单回答"请求从哪个网络地址来的"。
白名单（Allowlist）：开启后，仅允许白名单列表中列出的IP地址发起请求，不在白名单内的IP一律被拒绝访问。白名单的防护逻辑是"默认全部拒绝，只放行已知IP"——这是一种最小权限原则的实践。在配置白名单时需要注意：如果API前面有负载均衡器（如Nginx、F5等）、API网关或反向代理，务必把网关/代理服务器的出口IP也加入白名单，否则经过网关转发的请求虽然来自合法调用方，但因为到达平台的IP是网关IP而非原始调用方IP，会被白名单拦截。
黑名单（Blocklist）：将非法或异常的IP加入黑名单后，来自该IP的所有调用请求将被直接拒绝。黑名单的典型使用场景是动态防御——当监控到某个IP在短时间内发起大量鉴权失败请求（疑似暴力破解AppKey）、或某个IP的请求量异常飙升（疑似爬虫或攻击脚本），将该IP加入黑名单快速阻断攻击。黑名单的作用与白名单互补：白名单做"准入控制"，黑名单做"攻击响应"。
组合策略建议：推荐采用"白名单为主、黑名单为辅"的配置策略。先通过白名单将API的访问来源精确限定在已知的业务系统IP和网关IP范围内，再通过黑名单动态封禁来自这些已知IP中出现的异常调用行为。两者叠加使用可以同时覆盖"防止未知来源访问"和"已知来源中的异常行为处置"两个安全维度。
4.3 第三道防线：流量控制——限定"用多少"
流量控制（Rate Limiting，速率限制）从调用频次维度保护后端服务的稳定性。流量控制分两个层级：
| 层级 | 控制指标 | 配置位置 | 粒度说明 |
|---|---|---|---|
| 服务级流控 | 并发数 + 日最大访问量 | API服务维护 → 流控管理 | 整个服务下所有API共享配额 |
| API级流控 | 并发数 + 日最大访问量 | 新增/编辑API → 流量控制 | 单个API的独立配额 |
并发数控制的是"同一时刻系统正在处理的请求数量上限"，它的防护目标是瞬间流量洪峰——比如某个业务系统在整点批量触发了几百个API调用，并发数限制确保同时进入数据库的请求不会超过后端数据库的连接池容量。日最大访问量控制的是"一天内系统处理的总请求数上限"，它的防护目标是持续低频但高总量的异常调用——比如某个调用脚本因为代码Bug写成了死循环，以每秒1个请求的速度低调运行，并发数永远不会触发，但持续24小时就是86400个请求，日最大访问量可以在总量层面拦住这种"温水煮青蛙"式的消耗。
两个指标从不同维度保护系统，建议在生产环境中同时设置合理的阈值。优先为交易类API（下单、支付等直接关联业务结果的接口）设置较低的日最大访问量，为查询类API（数据列表、统计报表等只读接口）设置较高的日最大访问量或复用服务级默认值。不填写代表无限制，仅建议在测试环境或内部工具类API中使用。
三道防线配置速查
| 防线 | 机制 | 解决的问题 | 配置路径 | 关键操作 |
|---|---|---|---|---|
| 第一道 | 鉴权（AppKey + SecretKey） | 验证调用者身份合法性 | API共享→API授权 | 创建AppKey/SecretKey，选择鉴权模式 |
| 第二道 | 白名单/黑名单 | 控制请求来源IP范围 | API共享→白名单/黑名单 | 添加/删除IP地址，开启/关闭开关 |
| 第三道 | 流量控制（并发数+日最大访问量） | 限制调用频次 | 服务维护/API管理 | 设置服务级和API级阈值 |
第五章 验证结果——发布后的监控与调用
5.1 调用测试
API发布并上线后，可以通过三种方式进行调用测试。第一种是使用平台内置的测试功能——在API管理列表中找到目标API，点击"测试"按钮，输入参数值后直接查看返回结果，这是快速验证最便捷的方式。第二种是使用Postman——一款流行的API调试工具——将平台生成的API文档中的请求地址、请求方法和参数填入，发送请求验证。第三种是在命令行中使用cURL工具发起HTTP请求验证，适合自动化测试脚本集成。
以下是一个典型的cURL调用示例（以签名模式为例，签名参数由平台提供的SDK工具包自动计算生成）：
curl -X GET "http://192.168.1.100:8080/customer/order/query?customerId=12345" \
-H "AppKey: your_app_key_value" \
-H "Timestamp: 1719654321" \
-H "Signature: (由HMAC-SHA1算法计算生成的签名值)"
验证时需要重点检查三个方面：返回数据的字段完整性（所有预期字段是否都出现在返回结果中）、数据准确性（查询条件和返回值的对应关系是否正确）、脱敏效果（敏感字段的输出是否符合脱敏规则设定）。如果发现SQL逻辑有问题，可以直接编辑API修改SQL后重新测试，无需像传统开发流程那样走"改代码→部署→重启服务"的流程。
5.2 调用分析——三维度监控
进入「数据共享→API共享」，平台从三个维度提供API调用数据的可视化监控分析，帮助运维人员实时掌握API的使用情况：
| 分析维度 | 入口 | 展示内容 |
|---|---|---|
| 服务维度 | API服务调用分析 | 每个API服务的每日调用量（成功次数/失败次数分别统计）、历史调用总量、今日实时调用量、日调用量趋势折线图 |
| 用户维度 | API用户调用分析 | 每个AppKey调用者的今日调用量（成功/失败数）、历史调用总量、日调用量趋势——用于识别哪个调用方的用量异常增长 |
| API维度 | API调用分析 | 每个API的今日调用量（成功/失败次数）、历史调用总量、日调用量趋势——用于定位哪个API是热点接口 |
三个维度的分析互相补充：服务维度的趋势图帮你发现某个业务域的调用量是否在持续增长（需要扩容），用户维度帮你发现某个调用方的调用行为是否异常（如某个AppKey的失败率突然从2%飙升到40%，说明该调用方可能对接有问题），API维度帮你发现哪些API被调用最频繁（可能需要做缓存优化或SQL调优）。
5.3 API质量监控
除调用量统计外，平台还提供"API集监控"功能用于持续的API质量检测。将需要监控的多个API加入一个测试集后，配置以下三种监测规则：
可用性监测：定期向API发送测试请求，检查响应状态码是否为200（HTTP协议中的成功响应代码），判断API服务是否正常运行。
正确性监测：检查响应报文（HTTP响应正文）中是否包含预期的关键内容——例如在返回JSON中验证是否包含"code":"success"字段——确保API不只"能通"，而是"通得对"。
响应时间监测：检测API的响应耗时是否在设定的毫秒阈值内，超出阈值即判定为性能异常。
当任一监测规则触发异常时，平台自动通过微信、短信、邮件三种渠道向指定联系人发送告警通知，告警信息中附带异常原因的初步诊断（例如"响应超时，耗时3200ms，超过阈值2000ms"、"返回状态码500，疑似后端数据库连接失败"），帮助运维人员快速定位问题根因。
第六章 配置速查模板
本章将全文分散在各章节中的配置项整合为一张速查表，方便读者在实际操作时对照参考。
| 配置维度 | 配置项 | 填写内容 | 说明 |
|---|---|---|---|
| 服务维护 | 服务名称 | 英文，如customer |
作为API地址前缀，字母开头，长度1-32位 |
| 服务显示名称 | 中文，如"客户数据服务" | 管理界面识别用，调用方不可见 | |
| 并发数 | 1-9999 | 服务级并发数上限，不填无限制 | |
| 日最大访问量 | 1-9999 | 服务级日调用总量上限，不填无限制 | |
| 自助API基本信息 | 请求方法 | GET / POST | 查询用GET，提交或复杂查询用POST |
| 鉴权模式 | 签名/简易/不鉴权 | 敏感数据用签名，内部用简易，测试用不鉴权+白名单 | |
| 数据源 | 共享库DS/治理库DW/应用库ADS | 推荐选DS层，也可按需选DW或ADS层 | |
| SQL语句 | SELECT ... WHERE field = ${param} |
支持${}占位符绑定查询参数 |
|
| 最大返回记录数 | 正整数，如10000 | 防止单次查询返回数据过多导致内存溢出 | |
| 数据集标识 | 字母开头，如student |
主子表嵌套时主表标识，子表引用${主表标识.字段} |
|
| 转换规则 | 脱敏 | 位置（开始/结束）+替换内容 | 身份证：位置4-14，替换为* |
| 值映射 | 原始值→目标值 | 如F→女、M→男 | |
| 日期格式化 | 格式字符串 | 如yyyy-MM-dd |
|
| 默认值填充 | 默认内容 | 字段值为空时自动填入 | |
| 流控（服务级+API级） | 并发数 | 1-9999 | 同一时刻正在处理的请求数上限 |
| 日最大访问量 | 1-9999 | 一天内总请求数上限 | |
| 访问控制 | 白名单 | IP地址列表 | 仅允许白名单IP访问（开启后生效） |
| 黑名单 | IP地址列表 | 拒绝黑名单IP访问 | |
| API授权 | AppKey / SecretKey | 系统自动生成 | 每个调用方分配一对，AppKey用于身份标识，SecretKey用于签名 |
第七章 避坑指南与方法论收尾
7.1 避坑指南
坑一：测试时选"不鉴权"，上线后忘记切回签名模式
在测试阶段，很多操作人员为了让调试过程更顺畅，选择了"不鉴权"模式，测试通过后填写上线检查清单时漏了"鉴权模式确认"这一项，直接把API发布上线。结果API在公网环境中没有任何身份验证措施，任何人知道了API地址就能直接通过浏览器或脚本拉取数据。这种情况的严重性取决于数据敏感度——如果是公开的天气数据还好说，如果是客户订单数据或个人敏感信息，后果就是数据泄露。正确的做法是：从新建API的时候就明确安全等级策略并立即选择对应的鉴权模式。测试环境如需降低鉴权门槛，可以用"简易模式+白名单限制测试IP"的组合替代裸奔的"不鉴权"模式。如果确实需要在测试阶段用"不鉴权"，务必在测试完成后的上线检查清单中把"切换鉴权模式"作为必检项。
坑二：流控只配了并发数，没配日最大访问量
并发数和日最大访问量是对应两种不同攻击形态的防护指标，不能互相替代。并发数挡的是"洪峰型"攻击——攻击者在极短时间内发起大量并发请求，希望打满数据库连接池让服务瘫痪。日最大访问量挡的是"渗透型"消耗——攻击者或Bug脚本用不高不低的频率持续请求，比如每秒1次，看上去很温和，但24小时不间断就是86400次调用，如果单次返回数据1MB，一天就被拖走近10GB数据。很多运维人员觉得"我设置了并发数就够了"，实际上并发数对这种"低速持久"行为完全没有反应——每次只有1个并发，远低于阈值。两项指标缺一不可，生产环境务必两项都设置。
坑三：白名单配了业务服务器的IP，忘了加API网关的IP
白名单开启后，白名单列表中的IP是唯一被允许发起请求的地址。如果API是通过API网关或反向代理（如Nginx、Kong、Zuul）对外暴露的，实际到达数据中台的TCP连接源IP是网关服务器的IP，而不是原始调用方业务服务器的IP。很多运维人员在配置白名单时只加了业务服务器的IP，结果网关代理过来的请求全部被拦截——从网关那边看请求超时，从数据中台这边看白名单拒绝日志里全是网关IP的拦截记录。排查的时候经常要来回对日志对齐时间戳才能发现是白名单漏配了网关IP。正确做法：在配置白名单时，把API调用链上所有中间节点的出口IP都列进去——包括业务服务器IP、网关服务器IP、负载均衡器IP等。
7.2 小反转——从"开发两天"到"配置十分钟"
回到第一章开头的那个场景。张工在没有数据中台之前，每次对外共享一个数据接口，需要经过"确认数据源→找开发排期→写Controller/Service/DAO代码→配鉴权机制→写接口文档→联调测试→部署上线"的全流程，按最顺利的情况估算也要两天。现在借助龙石数据中台的数据共享模块，流程简化为"进入资产目录→找到目标表→新建自助API→编写SQL语句→选择鉴权模式→开启白名单→设置流控→测试发布"，八个步骤全程在可视化界面中完成，不需要写一行代码，全流程稳定控制在十分钟以内。而且这不仅是一次性的效率提升——后续的调用量统计、调用方管理、质量监控、异常告警全部由平台自动运转，张工不再需要被动地等业务部门来问"接口能不能用""为什么返回慢了""这个月调了多少次"，所有数据在监控面板上一目了然。从"有人找才响应"变成了"系统自动管"，这才是数据共享模块解决的核心问题——不只是省了两天开发时间，而是把数据共享这件事从"项目制的手工作坊"变成了"平台化的标准流水线"。
7.3 方法论收尾
龙石数据中台遵循"理、采、存、管、用"五阶方法论。前四个阶段——"理"清数据战略与业务方向、"采"集汇聚多源异构数据、"存"入分层模型的数据仓库、"管"控数据质量与标准规范——所有的投入和建设，最终都要在"用"这一阶段兑现业务价值。API共享模块正是"用"阶段的核心能力载体之一：它不是在简单地"把数据扔出去"，而是在"服务维护→鉴权授权→黑白名单访问控制→双层流量管控→多维度调用分析→持续质量监控"的一整套机制框架下，实现数据在"用得出去"和"管得住、看得清"之间取得平衡。
在江苏某数据局的共享交换平台中，全市百余个政务节点、近4万个交换任务、千余个API服务稳定运行，库表交换量累计近千亿条，API实时交换支撑跨省通办业务实现毫秒级数据核验；在某211大学的智慧校园项目中，基于数据中台搭建的数据超市上线后，跨部门数据申请从以往的"天/周级"线下审批模式缩短到"分钟级"在线自助获取，人力处、学生处、教务处等数十个部门的数据共享效率显著提升。这些案例背后验证的核心逻辑是：数据共享的价值不在于"技术有多复杂"，而在于"访问有多简单、管控有多精细"。让数据在安全可控的前提下高效流动，才是数据中台建设的最终目的。
FAQ
1. 三种鉴权模式怎么选？签名模式、简易模式、不鉴权各自适用什么场景？
签名模式基于HMAC-SHA1算法对每次请求参数动态生成签名摘要，每次请求签名不同，可有效防止重放攻击（攻击者截获一次合法请求后不能直接重复使用），适用于交易数据、财务数据、个人信息等敏感场景。简易模式仅校验AppKey是否存在且有效，不验证请求内容是否被篡改，对接复杂度低但安全等级居中，适用于内部系统之间的非敏感数据查询或低频调用。不鉴权不采取任何身份验证措施，适用于公开数据或测试环境，但必须同时开启白名单保护以限制访问来源范围。三种模式可由调用场景的数据敏感度和网络环境综合决定。
2. 白名单和鉴权能同时开启吗？不鉴权的API开启白名单后安全吗？
可以同时开启。鉴权验证"调用者是谁"（身份认证），白名单验证"请求从哪来"（来源限制），两者是互补的安全维度，不存在互斥关系。同时开启时，请求必须同时满足"AppKey合法（或签名验证通过）"和"来源IP在白名单内"两个条件才能通过。不鉴权的API开启白名单后，虽然不验证调用者身份，但只有白名单中的IP才能发起请求——适合完全信任的内网环境（内网IP本身就是一种身份背书）或对外提供只读公开数据的场景。
3. 并发数和日最大访问量分别控制什么？不填写代表什么？
并发数控制同一时刻系统正在处理的请求数量上限，防护目标是瞬间流量洪峰（如定时任务批量触发调用）。日最大访问量控制一天内系统处理的总请求数上限，防护目标是持续低频但高总量的异常调用（如脚本Bug导致的长时间循环调用）。两个指标从瞬间峰值和持续总量两个维度互补防护，不能互相替代。不填写代表无限制，建议生产环境两项均设置合理阈值。
4. 自助API和穿透API有什么区别？什么时候用哪个？
自助API是通过自定义SQL从数据库直接查询数据生成全新的API，属于零代码新建模式，API的逻辑在数据中台内部运行。穿透API是将已有的第三方API注册到数据中台统一纳管，不改原API逻辑，平台作为代理层提供地址转换、统一鉴权、调用日志等附加能力。如果数据存储在龙石数据中台的共享库中，用自助API直接在平台上创建；如果已有现成的外部API需要统一管理、监控和鉴权，用穿透API纳管。
5. API服务下线后已有的调用方会怎样？重新上线能恢复吗？
服务下线后，该服务下所有API将立即停止响应，调用方会收到HTTP连接失败或超时错误（具体取决于网关配置）。再次点击"上线"按钮后API调用立即恢复正常——不会丢失任何配置信息，不会影响已有的AppKey/SecretKey授权关系，也不会清空调用统计历史数据。服务下线是一个可逆的管理操作，常用于维护窗口期或紧急安全处置场景。
6. 自助API支持哪些数据库类型？查的是哪个库的数据？
自助API支持MySQL、Oracle、SQLServer、PostgreSQL、DM8（达梦数据库）、Doris（Apache Doris分析型数据库）、Vastbase_G100（海量数据库）等主流数据库。查询的数据源在创建API时自由选择——推荐选择共享库DS层，因为DS层是数据中台五层架构（SRC→ODS→DW→ADS→DS）中对外提供数据共享服务的统一出口，DS层的数据已经过完整的质量校验和标准化处理。
7. 如何监控API的可用性和正确性？
进入「数据共享→API共享」中的"API集监控"功能，将需要监控的多个API加入一个测试集，配置三种监测规则：可用性监测（检查响应状态码是否为200，确保服务正常运行）、正确性监测（检查响应报文中是否包含预期关键内容，如"code":"success"，确保API逻辑正常）、响应时间监测（检测响应耗时是否在设定的毫秒阈值内）。任一规则触发异常时，平台自动通过微信、短信、邮件三种渠道向指定联系人发送告警，告警信息附带异常原因便于快速定位。
8. 编排API能做什么自助API做不到的事？
编排API的核心能力是服务聚合与流程编排。它可以一次请求协调调用多个独立的自助API或外部API并融合返回结果（如同时查订单信息和用户信息合并返回），可以按条件判断走不同分支（如根据订单金额是否大于阈值决定走不同的审批流程），可以在编排画布中嵌入自定义Java逻辑处理复杂计算，可以实现跨多库的事务性操作（如订单创建同步扣减库存和更新用户积分，三个操作要么全部成功要么全部回滚）。自助API本质是"一个SQL→一个API"的一对一映射，编排API是"多个API+流程控制+事务管理→一个聚合API"的多对一编排。
本文为操作实践指南，所述操作路径和配置参数基于龙石数据中台产品公开功能。文中案例数据来自公开的项目建设成果通报及相关文献资料，供读者参考。
参考来源：
DAMA International，《DAMA数据管理知识体系指南（第二版）》（DAMA-DMBOK2），机械工业出版社，2020年。
