902 协议文件及脚本引用参数命名规范

版本: v1.0 修改日期: 2026-05-29 面向用户: 实施工程师 / 研发人员 / 协议对接人员

本规范统一 viSCADA 平台协议对接过程中的文件命名与参数命名方式,帮助团队降低沟通成本、减少字段重复与歧义,提升跨脚本协作与长期维护效率。本文档适用于新增协议脚本与已有脚本改造两种场景。

1 文件命名规范

1.1 命名格式

协议文件统一采用如下格式:


[数据对接厂家产品名称]_([协议类型])

ℹ️ 下划线 _ 与括号 () 均使用半角英文符号。

1.2 命名示例


海康威视摄像平台_(HTTP)
大华门禁系统_(MQTT)
Oracle业务库_(SQL)

1.3 命名要求

名称能直接体现「对接谁、用什么协议」
禁止使用无意义名称,如 test、demo、脚本1
协议类型必须与实际接入方式一致

1.4 协议类型与 Telegraf 插件对照

填写协议类型时请参照下表,避免名称不一致:

Telegraf 插件	Plugin ID	协议类型
MQTT Consumer	`inputs.mqtt_consumer`	MQTT
HTTP	`inputs.http`	HTTP
HTTP Listener v2	`inputs.http_listener_v2`	Webhook
Modbus	`inputs.modbus`	Modbus
OPC UA Client Reader	`inputs.opcua`	OPCUA
Siemens S7	`inputs.s7comm`	S7
Apache Kafka Consumer	`inputs.kafka_consumer`	Kafka
SQL	`inputs.sql`	SQL

2 参数命名通用规则

2.1 统一使用小驼峰命名

写法	是否推荐
`baseUrl`	✅
`connectTimeoutMs`	✅
`base_url`	❌ 下划线
`BaseUrl`	❌ 大驼峰

2.2 同一含义只保留一个名字

统一用 baseUrl,不要同时出现 url、apiUrl、requestUrl 表示同一意思。

2.3 同类脚本命名保持一致

所有脚本统一使用:host、port、username、password。

2.4 带单位的参数必须写清单位

connectTimeoutMs(毫秒)
retryIntervalMs(毫秒)
maxBytes(字节)

2.5 布尔值统一用 `is` / `enable` 开头

isSsl
enableCompression

2.6 敏感字段禁止明文打印

如 password、token、secretKey、clientSecret 等字段,日志输出必须脱敏处理。

3 参数专项规范

3.1 地址类参数

3.1.1 标准参数表

参数名	含义	示例
`host`	主机/IP,不带协议和端口	`127.0.0.1`
`port`	端口	`8080`
`baseUrl`	协议 + host + port	`http://127.0.0.1:8080`
`endpointPath`	接口路径	`/api/v1/device/status`
`requestUrl`	完整请求地址	`http://127.0.0.1:8080/api/v1/device/status`

3.1.2 使用规则

⚠️ requestUrl 与 baseUrl + endpointPath 二选一,不要同时配置两套。

如保留 address 字段,只允许写成 host:port 形式。

3.2 认证类参数

3.2.1 标准参数表

参数名	含义
`authType`	认证方式
`username`	用户名
`password`	密码
`token`	Bearer Token
`apiKeyName`	API Key 名称
`apiKeyValue`	API Key 值
`apiKeyIn`	位置:`header` / `query`
`accessKey`	访问密钥
`secretKey`	密钥
`clientId`	客户端 ID
`clientSecret`	客户端密钥

3.2.2 authType 推荐值

值	含义
`none`	无认证
`basic`	Basic 基础认证
`bearerToken`	Bearer Token 认证
`apiKey`	API Key 认证
`hmac`	HMAC 签名认证
`oauth2ClientCredentials`	OAuth2 客户端凭证
`tlsMutual`	TLS 双向认证

3.3 运行控制类参数

3.3.1 标准参数表

参数名	含义
`connectTimeoutMs`	连接超时(毫秒)
`readTimeoutMs`	读取超时(毫秒)
`writeTimeoutMs`	写入超时(毫秒)
`retryCount`	重试次数
`retryIntervalMs`	重试间隔(毫秒)
`batchSize`	批量大小
`maxRecords`	最大记录数
`pageNo`	页码
`pageSize`	每页条数
`dataFormat`	数据格式

3.3.2 dataFormat 推荐值

值	说明
`json`	JSON 格式
`xml`	XML 格式
`csv`	CSV 格式
`avro`	Apache Avro 格式
`protobuf`	Protocol Buffers 格式

4 常见协议参数规范

4.1 HTTP / HTTPS

参数名	说明
`httpMethod`	请求方法
`headers`	请求头
`queryParams`	Query 参数
`body`	请求体
`contentType`	内容类型
`accept`	接收类型
`authType`	认证方式
`token`	Bearer Token
`username`	Basic 用户名
`password`	Basic 密码
`proxyHost`	代理主机
`proxyPort`	代理端口

4.2 MQTT

参数名	说明
`brokerUrl`	Broker 地址
`clientId`	客户端 ID
`username`	用户名
`password`	密码
`topic`	主题

⚠️ MQTT 统一使用 brokerUrl,不要混用 baseUrl、requestUrl。

4.3 Kafka

参数名	说明
`bootstrapServers`	集群地址
`topic`	Topic 名称
`groupId`	消费组
`clientId`	客户端 ID
`securityProtocol`	安全协议
`saslMechanism`	SASL 机制
`saslUsername`	SASL 用户名
`saslPassword`	SASL 密码

4.4 JDBC / 数据库

参数名	说明
`databaseType`	数据库类型
`jdbcUrl`	JDBC 连接串
`username`	用户名
`password`	密码
`schemaName`	schema 名称
`tableName`	表名
`fieldName`	字段名
`sql`	SQL 语句

⚠️ 数据库场景优先使用 jdbcUrl,不要同时写 host、port、databaseName 等多套参数。

5 参考模板

以下模板给出典型协议的参数最小集合,可直接套用到新脚本。敏感字段使用 ****** 占位,实际填写时替换为真实值。

5.1 HTTP 模板


baseUrl=https://api.xxx.com
endpointPath=/api/v1/data
httpMethod=POST
contentType=application/json
authType=bearerToken
token=******
connectTimeoutMs=5000
readTimeoutMs=15000
retryCount=3
retryIntervalMs=1000

5.2 MQTT 模板


brokerUrl=tcp://127.0.0.1:1883
clientId=client_001
username=u1
password=******
topic=device/status
connectTimeoutMs=5000
retryCount=3
retryIntervalMs=1000

5.3 JDBC 模板


databaseType=mysql
jdbcUrl=jdbc:mysql://127.0.0.1:3306/testdb
username=dbuser
password=******
sql=select * from device_info
connectTimeoutMs=5000
readTimeoutMs=15000

6 规范落地检查清单

在提交或评审脚本前,请逐项核对:

💡 建议:每次评审脚本时按本清单逐项勾选,未勾选项需在评审意见中明确说明原因。长期保持清单习惯,可显著降低跨脚本协作的认知负担。