《面向統(tǒng)一電力數(shù)據(jù)中心的應(yīng)用開發(fā)技術(shù)規(guī)范》

ICS27.100

CCSF21

T/CES

團(tuán)體標(biāo)準(zhǔn)

T/CESXXX—2023

面向統(tǒng)一電力數(shù)據(jù)中心的應(yīng)用開發(fā)技術(shù)規(guī)

范

Dataaccessspecificationforpowerdatacenters

（工作組討論稿）

2023-XX-XX發(fā)布2023-XX-XX實(shí)施

中國(guó)電工技術(shù)學(xué)會(huì)?發(fā)布

T/CESXXX—2023

面向統(tǒng)一電力數(shù)據(jù)中心的應(yīng)用開發(fā)技術(shù)規(guī)范

1范圍

本文件規(guī)定了電力數(shù)據(jù)中心數(shù)據(jù)訪問的數(shù)據(jù)訪問性能、通訊協(xié)議、數(shù)據(jù)訪問方法、訪問安全等內(nèi)容。

本文件適用于電力數(shù)據(jù)中心的數(shù)據(jù)訪問。

2規(guī)范性引用文件

下列文件中的內(nèi)容通過文中的規(guī)范性引用而構(gòu)成本文件必不可少的條款。其中，注日期的引用文件，

僅該日期對(duì)應(yīng)的版本適用于本文件；不注日期的引用文件，其最新版本（包括所有的修改單）適用于本

文件。

GB/T22239信息安全技術(shù)網(wǎng)絡(luò)安全等級(jí)保護(hù)基本要求

GB35114公共安全視頻監(jiān)控聯(lián)網(wǎng)信息安全技術(shù)要求

DL/T2424智能電網(wǎng)術(shù)語(yǔ)

3術(shù)語(yǔ)和定義

DL/T2424界定的以及下列術(shù)語(yǔ)和定義適用于本文件。

3.1

電力數(shù)據(jù)powerdata

在發(fā)、輸、變、配、用等各環(huán)節(jié)所采集、加工與分析而取得的電力相關(guān)業(yè)務(wù)數(shù)據(jù)集合。

3.2

電力數(shù)據(jù)中心powerdatacenter

電力IT架構(gòu)的底層基礎(chǔ)設(shè)施，具備數(shù)據(jù)統(tǒng)一存儲(chǔ)、計(jì)算、分析和服務(wù)四大功能，提供海量數(shù)據(jù)存儲(chǔ)

處理、計(jì)算處理、分析挖掘等基礎(chǔ)性服務(wù)，支持采集測(cè)量、在線監(jiān)測(cè)、離線分析和實(shí)時(shí)計(jì)算等類型業(yè)務(wù)

應(yīng)用建設(shè)的平臺(tái)。

3.3

接入access

利用某種裝置或工具，將業(yè)務(wù)系統(tǒng)、電網(wǎng)運(yùn)行管理系統(tǒng)、計(jì)量自動(dòng)化系統(tǒng)及其它專業(yè)系統(tǒng)等系統(tǒng)的

數(shù)據(jù)及外部數(shù)據(jù)接入到電力數(shù)據(jù)中心的過程。包括了多種類型的電力數(shù)據(jù)源接入，如結(jié)構(gòu)化數(shù)據(jù)庫(kù)、非

結(jié)構(gòu)化文件、API接口、流式數(shù)據(jù)等。

3.4

接口interface

系統(tǒng)與另一個(gè)系統(tǒng)之間的公共邊界，信息通過該公共邊界傳遞。

3.5

數(shù)據(jù)模型datamodel

覆蓋資產(chǎn)、營(yíng)銷、人資、財(cái)務(wù)、綜合等業(yè)務(wù)領(lǐng)域的數(shù)據(jù)集合，由概念模型、邏輯模型、物理模型等

組成。

3.6

服務(wù)接口serviceinterface

1

T/CESXXX—2023

特定功能的形式化描述，定義了實(shí)現(xiàn)功能所需的參數(shù)和返回結(jié)果。

3.7

服務(wù)調(diào)用者serviceconsumer

根據(jù)服務(wù)接口描述訪問服務(wù)的程序。

3.8

服務(wù)提供者serviceprovider

實(shí)行服務(wù)接口定義的功能并提供服務(wù)的程序。

4縮略語(yǔ)

以下縮略語(yǔ)適用于本文件。

API：應(yīng)用編程接口（ApplicationProgrammingInterface）

AK/SK：訪問密鑰（AccessKey/SecretAccessKey）

CPU：中央處理器（CentralProcessingUnit）

HTTP：超文本傳輸協(xié)議（HyperTextTransferProtocol）

HTTPS：超文本傳輸安全協(xié)議（HyperTextTransferProtocolOverSecureSocketLayer）

IP：網(wǎng)際互連協(xié)議（InternetProtocol）

IT：互聯(lián)網(wǎng)技術(shù)（InternetTechnology）

JSON：JavaScript對(duì)象標(biāo)記（JavaScriptObjectNotation）

MTBF：平均故障間隔時(shí)間（MeanTimebetweenFailures）

MTTR：最長(zhǎng)修理時(shí)間（MaximumTimeToRepair）

PC：個(gè)人計(jì)算機(jī)（PersonalComputer）

TPS：并發(fā)數(shù)（TransactionsPerSecond）

VPN：虛擬專用網(wǎng)絡(luò)（VirtualPrivateNetwork）

REST：表述性狀態(tài)轉(zhuǎn)移（RepresentationalStateTransfer）

RESTFUL：一種網(wǎng)絡(luò)應(yīng)用程序的設(shè)計(jì)風(fēng)格和開發(fā)方式（RepresentationalStateTransfer）

SOAP：簡(jiǎn)單對(duì)象訪問協(xié)議（SimpleObjectAccessProtocol）

TCP：傳輸控制協(xié)議（TransmissionControlProtocol）

URI：統(tǒng)一資源標(biāo)識(shí)符（UniformResourceIdentifier）

URL：統(tǒng)一資源定位符（UniformResourceLocator）

UTF-8：針對(duì)Unicode的可變長(zhǎng)度字符編碼（8-bitUnicodeTransformationFormat）

WSDL：Web服務(wù)描述語(yǔ)言（WebServicesDescriptionLanguage）

XML：可擴(kuò)展標(biāo)記語(yǔ)言（ExtensibleMarkupLanguage）

5總則

5.1概述

數(shù)據(jù)應(yīng)用系統(tǒng)通過統(tǒng)一的API接口與電力數(shù)據(jù)中心的數(shù)據(jù)對(duì)接，滿足PC、WEB、移動(dòng)終端等應(yīng)用，還

包含數(shù)據(jù)訪問方法、訪問安全、通信協(xié)議等接入。技術(shù)架構(gòu)如圖1所示。

2

T/CESXXX—2023

圖1電力數(shù)據(jù)中心的數(shù)據(jù)應(yīng)用系統(tǒng)功能架構(gòu)示意圖

5.2數(shù)據(jù)服務(wù)接口需求和設(shè)計(jì)

5.2.1數(shù)據(jù)服務(wù)接口需求由數(shù)據(jù)服務(wù)調(diào)用者或數(shù)據(jù)服務(wù)提供者提出，具體應(yīng)滿足：

a)數(shù)據(jù)服務(wù)調(diào)用者評(píng)估使用需求，對(duì)暫無相應(yīng)數(shù)據(jù)服務(wù)接口的數(shù)據(jù)集提出服務(wù)接口生成需求；

b)數(shù)據(jù)服務(wù)提供者進(jìn)行需求調(diào)研，對(duì)有使用需求或有較高使用價(jià)值的數(shù)據(jù)集提出服務(wù)接口生成

需求；

c)數(shù)據(jù)歸口管理部門對(duì)數(shù)據(jù)服務(wù)接口生成需求進(jìn)行審核。

5.2.2數(shù)據(jù)服務(wù)接口運(yùn)行維護(hù)可參考附錄G，數(shù)據(jù)服務(wù)接口設(shè)計(jì)應(yīng)遵循以下要求：

a)以業(yè)務(wù)應(yīng)用需求為驅(qū)動(dòng)，按需進(jìn)行服務(wù)的生成，遵循企業(yè)級(jí)服務(wù)沉淀共享原則，避免重復(fù)生

成同一類型、同一性質(zhì)的服務(wù)接口；

b)按照電力數(shù)據(jù)中心數(shù)據(jù)存儲(chǔ)分層架構(gòu)設(shè)計(jì)，基于共享層、分析層數(shù)據(jù)進(jìn)行數(shù)據(jù)服務(wù)接口生成，

不宜基于貼源層生成服務(wù)接口；

c)按照數(shù)據(jù)分級(jí)權(quán)限進(jìn)行數(shù)據(jù)服務(wù)接口訪問控制，根據(jù)數(shù)據(jù)業(yè)務(wù)特點(diǎn)及應(yīng)用特點(diǎn)設(shè)置服務(wù)接口

的有效期約束。

5.3服務(wù)注冊(cè)

5.3.1電力數(shù)據(jù)中心相關(guān)的數(shù)據(jù)服務(wù)應(yīng)基于數(shù)據(jù)服務(wù)組件進(jìn)行統(tǒng)一注冊(cè)、發(fā)布，并對(duì)外提供服務(wù)調(diào)用。

服務(wù)引擎注冊(cè)以“一表一服務(wù)”為原則。

5.3.2在接口開發(fā)過程需遵循數(shù)據(jù)服務(wù)開發(fā)規(guī)范，應(yīng)包括但不限于編碼設(shè)置、接口邏輯、接口返回體、

程序異常處理操作、程序打包，分別見附錄A～E。

5.3.3用戶通過上傳程序包、填寫服務(wù)使用規(guī)則等信息進(jìn)行服務(wù)注冊(cè)申請(qǐng)，步驟應(yīng)滿足：

a)上傳程序包：上傳注冊(cè)至系統(tǒng)的服務(wù)程序包；

b)服務(wù)接口參數(shù)：系統(tǒng)解析出來程序包中的服務(wù)請(qǐng)求參數(shù)和響應(yīng)參數(shù)；

c)服務(wù)基本信息：服務(wù)基本信息填寫表單；

d)完成：成功提交服務(wù)注冊(cè)申請(qǐng)，進(jìn)入審批。

3

T/CESXXX—2023

5.3.4數(shù)據(jù)服務(wù)接口發(fā)布應(yīng)基于數(shù)據(jù)中臺(tái)數(shù)據(jù)服務(wù)組件完成，包括操作請(qǐng)求和返回應(yīng)答兩部分。數(shù)據(jù)

服務(wù)接口發(fā)布請(qǐng)求參數(shù)和返回參數(shù)包括但不限于表1內(nèi)容。

表1數(shù)據(jù)服務(wù)接口發(fā)布請(qǐng)求參數(shù)

序號(hào)名稱說明

API名稱應(yīng)由數(shù)據(jù)服務(wù)提供者組織機(jī)構(gòu)、數(shù)據(jù)服務(wù)所屬應(yīng)用域、自定義字段和版

1APIName

本號(hào)四部分組成

發(fā)布請(qǐng)求參數(shù)

2StageName運(yùn)行環(huán)境名稱，取值為生產(chǎn)環(huán)境或測(cè)試環(huán)境

3Description授權(quán)說明

4發(fā)布返回參數(shù)RequestId請(qǐng)求唯一標(biāo)識(shí)

5.3.5數(shù)據(jù)服務(wù)接口查看應(yīng)基于數(shù)據(jù)中臺(tái)數(shù)據(jù)服務(wù)組件完成，包括操作請(qǐng)求和返回應(yīng)答兩部分。數(shù)據(jù)

服務(wù)接口查看請(qǐng)求和返回參數(shù)包括但不限于表2內(nèi)容。

表2數(shù)據(jù)服務(wù)接口查看請(qǐng)求參數(shù)

序號(hào)名稱說明

1APIId指定的API編號(hào)

2APINameAPI名稱（模糊匹配）

3查看請(qǐng)求參數(shù)StageName運(yùn)行環(huán)境名稱，取值為生產(chǎn)環(huán)境或測(cè)試環(huán)境

4PageSize指定分頁(yè)查詢時(shí)每頁(yè)行數(shù)

5PageNumber指定要查詢的頁(yè)碼

6RequestId本次請(qǐng)求編號(hào)

7TotalCount返回結(jié)果的總條數(shù)

查看返回參數(shù)

8PageNumber返回指定的頁(yè)碼

9PageSize返回指定的每頁(yè)條數(shù)

6通訊協(xié)議

6.1協(xié)議格式

服務(wù)接口集成以WebService和RESTService為載體，相關(guān)協(xié)議要求見表3。

表3WebService和RESTService協(xié)議棧

項(xiàng)目協(xié)議

服務(wù)發(fā)現(xiàn)層UDDI

服務(wù)描述層WSDL

WebService協(xié)議棧

消息封裝層SOAP

服務(wù)傳輸層HTTP、HTTPS

服務(wù)發(fā)現(xiàn)層無

服務(wù)描述層URI

RESTService協(xié)議棧

消息封裝層JSON

服務(wù)傳輸層HTTP、HTTPS

6.2數(shù)據(jù)格式

4

T/CESXXX—2023

6.2.1WebService應(yīng)采用基于XML的數(shù)據(jù)格式。

6.2.2RESTService應(yīng)采用基于JSON的數(shù)據(jù)格式。

6.3URL約定

一個(gè)資源應(yīng)具有一個(gè)或多個(gè)標(biāo)識(shí)，采用URL作為資源標(biāo)識(shí)。路徑變量可說明資源層次結(jié)構(gòu)，URL全部

采用小寫字母及數(shù)字，至少兩層，根據(jù)場(chǎng)景支持多級(jí)分類。URL定義規(guī)則如下，說明見表4：

{通信協(xié)議}//{數(shù)據(jù)服務(wù)網(wǎng)關(guān)地址}/{服務(wù)所屬應(yīng)用域}/{版本號(hào)}/{子目錄}/…/{子目錄}

表4資源標(biāo)識(shí)元素

序號(hào)元素名稱說明

1通信協(xié)議服務(wù)接口與調(diào)用請(qǐng)求之間的通信協(xié)議，使用HTTP或HTTPS的一種

2數(shù)據(jù)服務(wù)網(wǎng)關(guān)地址數(shù)據(jù)服務(wù)網(wǎng)關(guān)IP地址或域名

3服務(wù)所屬應(yīng)用域根據(jù)業(yè)務(wù)部門使用場(chǎng)景簡(jiǎn)稱劃分

4版本號(hào)服務(wù)接口的版本信息，如V1.0.0

根據(jù)服務(wù)業(yè)務(wù)分類自主確定，各級(jí)子目錄的命名如果涉及到多個(gè)單詞，應(yīng)采用駱駝命名

5子目錄

法，即第一個(gè)單詞為小寫，隨后的單詞第一個(gè)字符大寫

7數(shù)據(jù)訪問方法

7.1數(shù)據(jù)訪問流程

服務(wù)提供者是服務(wù)的被調(diào)用方，即該服務(wù)提供服務(wù)給其他服務(wù)。服務(wù)消費(fèi)者是服務(wù)的調(diào)用方，即該

服務(wù)調(diào)用服務(wù)提供者提供的服務(wù)。數(shù)據(jù)服務(wù)接口由使用者發(fā)起請(qǐng)求，電力數(shù)據(jù)中心相關(guān)組件處理請(qǐng)求，

具體交互過程應(yīng)滿足：

a)服務(wù)提供者基于數(shù)據(jù)服務(wù)組件注冊(cè)相關(guān)數(shù)據(jù)服務(wù)接口定義信息，支持電力數(shù)據(jù)中心各組件API

接口及第三方接口的注冊(cè)；

b)服務(wù)調(diào)用者通過數(shù)據(jù)服務(wù)組件查詢數(shù)據(jù)服務(wù)接口定義信息；

c)服務(wù)調(diào)用者獲取數(shù)據(jù)服務(wù)接口定義信息；

d)服務(wù)調(diào)用者向數(shù)據(jù)服務(wù)組件發(fā)起數(shù)據(jù)服務(wù)接口請(qǐng)求，數(shù)據(jù)服務(wù)組件請(qǐng)求進(jìn)行鑒權(quán)、路由等

處理，并將請(qǐng)求轉(zhuǎn)發(fā)到相關(guān)組件或第三方接口；

e)服務(wù)提供者接收數(shù)據(jù)服務(wù)接口請(qǐng)求；

f)服務(wù)提供者對(duì)請(qǐng)求進(jìn)行處理，并返回?cái)?shù)據(jù)服務(wù)接口應(yīng)答信息至數(shù)據(jù)服務(wù)組件，由數(shù)據(jù)服務(wù)組

件對(duì)響應(yīng)進(jìn)行路由、轉(zhuǎn)換等處理，并轉(zhuǎn)發(fā)到服務(wù)調(diào)用者；

g)服務(wù)調(diào)用者接收數(shù)據(jù)服務(wù)接口應(yīng)答結(jié)果。

7.2服務(wù)申請(qǐng)

7.2.1數(shù)據(jù)服務(wù)引擎應(yīng)支持以RESTFULAPI形式提供數(shù)據(jù)。數(shù)據(jù)范圍按當(dāng)前業(yè)務(wù)的真實(shí)需求選擇，獲

取權(quán)限后僅可訪問權(quán)限范圍內(nèi)的數(shù)據(jù)。若后續(xù)業(yè)務(wù)需求變更，需要變更數(shù)據(jù)范圍，則可在數(shù)據(jù)服務(wù)引擎

中進(jìn)行權(quán)限變更操作，重新發(fā)起數(shù)據(jù)權(quán)限申請(qǐng)。

7.2.2進(jìn)行服務(wù)申請(qǐng)時(shí)，應(yīng)先進(jìn)行應(yīng)用信息登記，登記應(yīng)遵循以下規(guī)范：

——應(yīng)用名稱：遵循應(yīng)用名稱命名規(guī)范進(jìn)行命名；

——應(yīng)用IP：為應(yīng)用部署IP，應(yīng)真實(shí)、有效；

——應(yīng)用用途：為字符串，不做限制，長(zhǎng)度為5～50個(gè)字符。

5

T/CESXXX—2023

7.2.3申請(qǐng)用途應(yīng)基于真實(shí)數(shù)據(jù)服務(wù)需求進(jìn)行申請(qǐng)說明，不應(yīng)編造。

7.3服務(wù)調(diào)用

7.3.1網(wǎng)絡(luò)策略

數(shù)據(jù)消費(fèi)應(yīng)用在正式調(diào)用前，數(shù)據(jù)消費(fèi)應(yīng)用到數(shù)據(jù)服務(wù)引擎間的網(wǎng)絡(luò)能正常訪問：

a）部門數(shù)據(jù)消費(fèi)應(yīng)用跨網(wǎng)段需要申請(qǐng)開通網(wǎng)絡(luò)策略；

b）子單位數(shù)據(jù)消費(fèi)應(yīng)用需在網(wǎng)側(cè)及子單位側(cè)均申請(qǐng)網(wǎng)絡(luò)策略。

7.3.2調(diào)用程序

服務(wù)申請(qǐng)審核通過后，通過獲取的密鑰信息，進(jìn)行服務(wù)調(diào)用，詳見附錄F。

7.3.3鑒權(quán)

服務(wù)消費(fèi)者訪問數(shù)據(jù)時(shí)，訪問權(quán)限和數(shù)據(jù)范圍都因應(yīng)用不同而不同，數(shù)據(jù)服務(wù)引擎應(yīng)確認(rèn)到

每次訪問的應(yīng)用信息，包括應(yīng)用信息、服務(wù)的訪問權(quán)限、權(quán)限數(shù)據(jù)范圍等，應(yīng)滿足：

a）應(yīng)用部署IP與應(yīng)用登記的應(yīng)用IP一致，否則將無法訪問；

b）調(diào)用數(shù)據(jù)在訪問權(quán)限數(shù)據(jù)范圍內(nèi)，否則無法正常訪問。

基于數(shù)據(jù)服務(wù)引擎給的訪問密鑰，AccessKey用于標(biāo)識(shí)應(yīng)用，SecretAccessKey是服務(wù)消

費(fèi)者用于加密認(rèn)證字符串和平臺(tái)用來驗(yàn)證認(rèn)證字符串的密鑰，服務(wù)消費(fèi)者在使用過程中SK應(yīng)保密。

8訪問安全

8.1基本要求

8.1.1應(yīng)符合GB/T22239、GB35114等網(wǎng)絡(luò)安全防護(hù)的相關(guān)規(guī)定。

8.1.2應(yīng)采用安全等級(jí)認(rèn)證機(jī)制。

8.1.3應(yīng)采用加密技術(shù)，實(shí)施賬號(hào)權(quán)限分配管理。

8.2系統(tǒng)安全

8.2.1應(yīng)及時(shí)安裝補(bǔ)丁，補(bǔ)丁安裝前應(yīng)進(jìn)行離線測(cè)試。

8.2.2應(yīng)進(jìn)行安全加固，關(guān)閉暫不使用的服務(wù)，設(shè)置關(guān)鍵配置文件的訪問權(quán)限，開啟日志審計(jì)功能。

8.2.3應(yīng)使用漏洞掃描工具每半個(gè)月對(duì)平臺(tái)漏洞進(jìn)行掃描，漏洞庫(kù)更新不應(yīng)超過24h，漏洞應(yīng)及時(shí)進(jìn)

行處理，容器應(yīng)進(jìn)行加密處理。

8.2.4應(yīng)支持對(duì)物聯(lián)網(wǎng)網(wǎng)關(guān)軟件包、補(bǔ)丁包、容器、APP進(jìn)行簽名校驗(yàn)。

8.3網(wǎng)絡(luò)安全

網(wǎng)絡(luò)安全應(yīng)滿足如下要求：

a)傳輸安全：

1)數(shù)據(jù)傳輸采用電力通信專網(wǎng)（光纖、非網(wǎng)絡(luò)專線等有線通信）方式時(shí)，生產(chǎn)控制大區(qū)的

終端滿足縱向加密認(rèn)證接入要求，管理信息大區(qū)的終端通過訪問控制措施滿足邊界防護(hù)

要求；

2)數(shù)據(jù)傳輸采用運(yùn)營(yíng)商公網(wǎng)（有線或無線通信）或因特網(wǎng)時(shí)，根據(jù)數(shù)據(jù)所接入的安全分區(qū)

采用相應(yīng)的安全防護(hù)措施；

3)終端在通過公網(wǎng)途徑傳輸數(shù)據(jù)時(shí)，采用國(guó)密VPN方式。

6

T/CESXXX—2023

h)接入安全：

1)通過有線（電力專線）、無線（自建無線網(wǎng)絡(luò)或公網(wǎng)無線網(wǎng)絡(luò)）接入現(xiàn)場(chǎng)網(wǎng)關(guān)（終端）

的節(jié)點(diǎn)，宜接入不同的設(shè)備；

2)電力專線與無線公網(wǎng)數(shù)據(jù)不應(yīng)混合接入傳輸。

c）終端安全：

1)具備電力數(shù)據(jù)中心的數(shù)據(jù)應(yīng)用系統(tǒng)可識(shí)別、防篡改和防擦除的唯一ID標(biāo)識(shí)；

2)具備內(nèi)嵌式或外接式的安全功能硬件；

3)具備身份鑒權(quán)認(rèn)證方式，身份鑒權(quán)認(rèn)證方式符合電力數(shù)據(jù)中心的數(shù)據(jù)應(yīng)用系統(tǒng)接入鑒權(quán)

要求；

4)采用符合國(guó)密的密碼算法；

5)系統(tǒng)URL接口應(yīng)接受每月的漏洞掃描，并根據(jù)掃描的結(jié)果進(jìn)行安全整改。

8.4接口安全

應(yīng)滿足以下要求：

a)對(duì)于涉密數(shù)據(jù)，進(jìn)行脫敏處理或者特殊加密；

b)數(shù)據(jù)服務(wù)接口安全日志應(yīng)保存6個(gè)月以上；

c)數(shù)據(jù)服務(wù)訪問權(quán)限按照數(shù)據(jù)分級(jí)、分類權(quán)限等級(jí)管理要求進(jìn)行授權(quán)管理。應(yīng)滿足：

1)數(shù)據(jù)服務(wù)接口授權(quán)：根據(jù)數(shù)據(jù)服務(wù)調(diào)用者申請(qǐng)的數(shù)據(jù)服務(wù)權(quán)限，進(jìn)行審核及授權(quán)。數(shù)據(jù)

服務(wù)接口授權(quán)應(yīng)基于數(shù)據(jù)中臺(tái)數(shù)據(jù)服務(wù)組件完成，包括操作請(qǐng)求和返回應(yīng)答兩部分，示

例見表5；

表5數(shù)據(jù)服務(wù)接口授權(quán)參數(shù)示例

序號(hào)名稱說明

1ApiIdApi唯一標(biāo)識(shí)編號(hào)，由系統(tǒng)生成

2StageName運(yùn)行環(huán)境名稱，取值為生產(chǎn)環(huán)境或測(cè)試環(huán)境

請(qǐng)求參數(shù)

3AppId指定要執(zhí)行授權(quán)操作的APP編號(hào)

4Description授權(quán)說明

5返回參數(shù)RequestId請(qǐng)求唯一標(biāo)識(shí)

2)數(shù)據(jù)服務(wù)接口認(rèn)證：應(yīng)選擇一種或多種認(rèn)證方式進(jìn)行認(rèn)證，見表6。

表6服務(wù)接口認(rèn)證方式

序號(hào)認(rèn)證方式說明

1APPKey認(rèn)證通過AppKey和AppSecret進(jìn)行簽名認(rèn)證

2Basic認(rèn)證采用HTTP的BASIC認(rèn)證方式，后端服務(wù)通過用戶名和密碼進(jìn)行認(rèn)證

3PublicKey認(rèn)證采用AuthAdv的TokenNE認(rèn)證，后端服務(wù)通過公鑰驗(yàn)證Token進(jìn)行認(rèn)證

4其他認(rèn)證可直接調(diào)用API，無需認(rèn)證，部分公開性信息，僅查詢類的接口可采用該方式

7

T/CESXXX—2023

A

A

附錄A

（規(guī)范性）

編碼設(shè)置

A.1模板程序目錄

A.1.1數(shù)據(jù)服務(wù)接口模板程序的目錄結(jié)構(gòu)應(yīng)包含公共常量、控制層、異常處理、日志記錄、實(shí)體類、

業(yè)務(wù)處理。

A.1.2各數(shù)據(jù)服務(wù)開發(fā)人員在開發(fā)過程中需將相應(yīng)功能的代碼對(duì)號(hào)存放，不隨意刪減模板程序中的目

錄、代碼。

A.2公共配置

數(shù)據(jù)服務(wù)引擎當(dāng)前推薦使用YAML文件格式進(jìn)行配置，程序中設(shè)定了以下幾個(gè)公共配置項(xiàng)。開發(fā)過程

中可根據(jù)本地實(shí)際情況進(jìn)行配置，代碼見示例。

示例1：注冊(cè)中心地址:

eureka:

client:

healthcheck:enabled

serviceUrl:

defaultZone:26:8061/eureka/，27:8061/eureka/，

36:8061/eureka/

示例2：程序訪問端號(hào)及訪問路徑：

server:

port:8080

context-path:/

示例3：端口監(jiān)控配置：

management:

security:

enabled:false

endpoints:

web:

exposure:

include:"*"

A.3自定義配置

A.3.1數(shù)據(jù)庫(kù)代碼見示例。

示例：數(shù)據(jù)庫(kù)：

spring:

datasource:

driver-class-name:com.mysql.jdbc.Driver

url:jdbc:mysql://ip:port/database_name?characterEncoding=UTF-8&useSSL=false

username:root

password:

8

T/CESXXX—2023

A.3.2在編碼過程中，應(yīng)將IDE中的字符編碼設(shè)置成UTF-8編碼程序命名。

A.4命名規(guī)范

A.4.1代碼中的命名均不能以下劃線或美元符號(hào)開始，也不能以下劃線或美元符號(hào)結(jié)束。

示例：反例：_name/__name/$name/name_/name$/name__

A.4.2代碼中的命名嚴(yán)禁使用拼音與英文混合的方式，更不可直接使用中文的方式。

示例1：正例：beijing/guangzhou等國(guó)際通用的名稱，可視同英文。

示例2：反例：CheXiaoOption[撤銷]/getfazhiByName（）[閥值]/int某變量=3

A.4.3類名使用UpperCamelCase風(fēng)格，下情形例外：DO/BO/DTO/VO/AO/PO/UID等。

示例1：正例：MarcoPolo/UserDO/XmlService/TcpUdpDeal/TaPromotion

示例2：反例：macroPolo/UserDo/XMLService/TCPUDPDeal/TAPromotion

A.4.4方法名、參數(shù)名、成員變量、局部變量都統(tǒng)一使用lowerCamelCase風(fēng)格，遵從駝峰式。

示例：正例：localValue/getHttpMessage（）/inputUserId

A.4.5常量命名全部大寫，單詞間用下劃線隔開，力求語(yǔ)義表達(dá)完整清楚，不要嫌名字長(zhǎng)。

示例1：正例：MAX_STOCK_COUNT

示例2：反例：MAX_COUNT

A.4.6抽象類命名使用Abstract或Base開頭；異常類命名使用Exception結(jié)尾；測(cè)試類命名以它要測(cè)試

的類的名稱開始，以Test結(jié)尾。

A.4.7類型與中括號(hào)緊挨相連來表示數(shù)組。

示例1：正例：定義整形數(shù)組int[]arrayDemo;

示例2：反例：在main參數(shù)中，使用Stringargs[]來定義。

A.4.8POJO類中布爾類型的變量，不要加is前綴，否則部分框架解析會(huì)引起序列化錯(cuò)誤。

示例：反例：定義為基本數(shù)據(jù)類型BooleanisDeleted的屬性，它的方法也是isDeleted（），RPC框架在反向解

析的時(shí)候，“誤以為”對(duì)應(yīng)的屬性名稱是deleted，導(dǎo)致屬性獲取不到，進(jìn)而拋出異常。

A.4.9包名統(tǒng)一使用小寫，點(diǎn)分隔符之間有且僅有一個(gè)自然語(yǔ)義的英語(yǔ)單詞。包名統(tǒng)一使用單數(shù)形式，

但是類名如果有復(fù)數(shù)含義，類名可使用復(fù)數(shù)形式。

示例：正例：應(yīng)用工具類包名為com.csg.dse.srvc.util、類名為MessageUtils（此規(guī)則參考spring的框架結(jié)構(gòu)）

A.4.10杜絕完全不規(guī)范的縮寫，避免望文不知義。

示例：反例：AbstractClass“縮寫”命名成AbsClass；condition“縮寫”命名成condi。

A.4.11數(shù)據(jù)服務(wù)名稱命名用于能夠容易的識(shí)別、檢索出某一服務(wù)，應(yīng)遵循：

——服務(wù)英文名命名為：字母開頭，只能包含字母下劃線和數(shù)字，長(zhǎng)度為3～27個(gè)字符，是服務(wù)

的唯一標(biāo)識(shí)。Jar包形式注冊(cè)，將取程序中定義的英文名稱為服務(wù)英文名稱，在程序中定義遵

循相同的命名規(guī)則；

——服務(wù)中文名命名為：為字符串，限制中文、英文、數(shù)字及下劃線，長(zhǎng)度在3～15個(gè)字符，長(zhǎng)

度50，為服務(wù)顯示的名稱，可重復(fù)。

A.4.12應(yīng)用名稱命名為字符串，限制中文、英文、數(shù)字及下劃線，長(zhǎng)度在5～15個(gè)字符，為應(yīng)用顯示

的名稱，可重復(fù)；系統(tǒng)生成應(yīng)用ID，為應(yīng)用的唯一標(biāo)識(shí)。

A.4.13系統(tǒng)間交互的數(shù)據(jù)編碼格式宜采用UTF-8字符集進(jìn)行編碼。

9

T/CESXXX—2023

B

B

附錄B

（規(guī)范性）

接口邏輯

B.1概述

在編寫接口邏輯代碼時(shí)，應(yīng)遵循控制器、參數(shù)、返回體編碼的要求，同時(shí)接口業(yè)務(wù)邏輯部份請(qǐng)遵循

編碼規(guī)約、注釋規(guī)范。

B.2控制器

RESTAPI方式數(shù)據(jù)服務(wù)接口模板程序，使用控制器（Controller）實(shí)現(xiàn)數(shù)據(jù)服務(wù)接口的定義，基于

springcloud原生架構(gòu)并在此基礎(chǔ)之上進(jìn)了擴(kuò)展，提供一些公共的組件能力，在開發(fā)過程中應(yīng)遵循及注

意的事項(xiàng)：

——Controller類統(tǒng)一引入org.springframework.web.bind.annotation注解，@RestController

聲明控制類，可使用@RequestMappinp聲明接口路徑；

——使用@PostMapping聲明接口請(qǐng)求方式，接口只支持post請(qǐng)求方式；

——Controller類應(yīng)繼承BaseController；

——使用@RequestBody聲明請(qǐng)求參數(shù)

示例：

@RequestMapping（"/Student"）

publicclassStudentControllerextendsBaseController{

@ResponseBody

@PostMapping（"/stuInfo"）

publicStudentReturnViewstuInfo（@RequestBodyMyInputViewinputView）{

StudentReturnViewview=newStudentReturnView（）;

view.setAge（String.valueOf（inputView.getAge（）））;

view.setName（inputView.getName（））;

returnview;

}

}

注：服務(wù)只支持可定義一個(gè)controller，controller里只能定義一個(gè)接口。

B.3接口參數(shù)

基于電力數(shù)據(jù)中心提供的模板程序定義數(shù)據(jù)服務(wù)接口時(shí)，接口參數(shù)部份需定義成一個(gè)VO類繼承基類

InputView，按要求使用統(tǒng)一的注解進(jìn)行標(biāo)注，用到的注解及注意事項(xiàng)如下：

——參數(shù)以post方式提供；

——接口入?yún)?yīng)自定義bean繼承InputView，并使用@RequestBody傳入?yún)?shù)；

——自定義bean的屬性只支持基礎(chǔ)數(shù)據(jù)類型；

——應(yīng)添加@ApiModelProperty對(duì)自定義的參數(shù)bean里面的屬性進(jìn)行描述，應(yīng)包含：

name：字段名；

dataType：參數(shù)類型（與方法傳參類型對(duì)應(yīng)）；

required：是否應(yīng)填；

value：字段描述；

example:默認(rèn)值（示例）。

10

T/CESXXX—2023

示例：

@ResponseBody

@PostMapping（"/stuInfo"）

publicStudentReturnViewsutInfo（@RequestBodyStuInputViewinputView）{

StudentReturnViewview=newStudentReturnView（）;

view.setAge（inputView.getAge（））;

view.setName（inputView.getName（））;

returnview;

}

@Data

publicclassStudentInputViewextendsInputView{

@ApiModelProperty（value="名稱"，name="name"，example="李明"，required=true）

privateStringname;

@ApiModelProperty（value="年齡"，name="age"，example="1"，required=true）

privateStringage;

11

T/CESXXX—2023

C

C

附錄C

（規(guī)范性）

接口返回體

C.1數(shù)據(jù)服務(wù)接口不可直接返回基礎(chǔ)數(shù)據(jù)類型，需統(tǒng)一返回自定義bean，自定義bean應(yīng)繼承

ReturnView。

C.2在自定義Bean中，應(yīng)添加@ApiModelProperty注解說明返回字段含義，打包的時(shí)候程序才可正確

生成接口的響應(yīng)參數(shù)描述文件，應(yīng)包含：

——value:字段描述；

——name：字段名；

——example：示例；

——required：是否一定有值。

C.3接口響應(yīng)參數(shù)實(shí)體，需包括code（狀態(tài)碼），msg（消息），viewObject（返回?cái)?shù)據(jù)）。

示例：

publicclassStudentReturnViewextendsReturnView{

@ApiModelProperty（value="學(xué)生ID"，name="stuId"，example="1"，required=true）

privateStringstuId;

@ApiModelProperty（value="學(xué)生名稱"，name="name"，example="小林"，required=true）

privateStringname;

@ApiModelProperty（value="學(xué)生年齡"，name="age"，example="19"，required=true）

privateStringage;

@ApiModelProperty（value="學(xué)生各分?jǐn)?shù)詳情"，name="scores"，example="{\"wuli\":90，\"yuwen\":100}"，

required=true）

privateList<Score>scores;

@ApiModelProperty（value="學(xué)生總分?jǐn)?shù)"，name="score"，example="100"，required=true）

privateScorescore;

12

T/CESXXX—2023

D

D

附錄D

（規(guī)范性）

程序異常處理操作

D.1服務(wù)發(fā)生系統(tǒng)錯(cuò)誤進(jìn)程停止后，容器會(huì)對(duì)該服務(wù)副本進(jìn)行自動(dòng)重啟，程序不應(yīng)對(duì)系統(tǒng)錯(cuò)誤進(jìn)行處

理。

D.2異常不要用來做流程控制，條件控制，因?yàn)楫惓５奶幚硇时葪l件分支低。

D.3不對(duì)大段代碼進(jìn)行try-catch，catch時(shí)請(qǐng)分清穩(wěn)定代碼和非穩(wěn)定代碼，穩(wěn)定代碼指的是無論如何

不會(huì)出錯(cuò)的代碼。對(duì)于非穩(wěn)定代碼的catch盡可能進(jìn)行區(qū)分異常類型，再進(jìn)行對(duì)應(yīng)的異常處理。

D.4有try塊放到了事務(wù)代碼中，catch異常后，如果回滾事務(wù)，應(yīng)手動(dòng)回滾事務(wù)。

D.5finally塊應(yīng)對(duì)資源對(duì)象、流對(duì)象進(jìn)行關(guān)閉，有異常也要做try-catch。

注：如果JDK7及以上，可以使用try-with-resources方式。

D.6不能在finally塊中使用return，finally塊中的return返回后方法結(jié)束執(zhí)行，不會(huì)再執(zhí)行try

塊中的return語(yǔ)句。

D.7捕獲異常與拋異常，應(yīng)完全匹配，或者捕獲異常是拋異常的父類。

D.8方法的返回值可為null，不強(qiáng)制返回空集合，或者空對(duì)象等，應(yīng)添加注釋充分說明什么情況下會(huì)

返回null值。調(diào)用方進(jìn)行null判斷防止NPE問題。

13

T/CESXXX—2023

E

E

附錄E

（規(guī)范性）

程序打包

E.1運(yùn)行環(huán)境

數(shù)據(jù)服務(wù)引擎當(dāng)前系統(tǒng)支持JRE1.8運(yùn)行環(huán)境，程序打包過程中請(qǐng)將jar包的運(yùn)行環(huán)境設(shè)置成JRE1.8。

E.2打包指令

基于模板程序開發(fā)的數(shù)據(jù)服務(wù)接口程序通過MAVEN進(jìn)行打包，通過執(zhí)行mvnpackage命令完成打包。

E.3程序包命名

程序maven編繹打包后會(huì)在target目錄下生成dse-srvc-template-xxx（版本號(hào)）.jar，可在pom.xml

文件自定義文件名及修改版本號(hào)。

E.4接口描述文件目錄

基于模板程序開發(fā)的數(shù)據(jù)服務(wù)接口程序，通過MAVEN打完包后會(huì)在JAR包的相應(yīng)目錄中生成接口描述

文件，如未正確生成此文件，將會(huì)無法在服務(wù)引擎中正常注冊(cè)，開發(fā)過程中應(yīng)遵守接口邏輯規(guī)范。

14

T/CESXXX—2023

F

F

附錄F

（規(guī)范性）

服務(wù)調(diào)用過程

F.1獲取AK/SK

服務(wù)申請(qǐng)審核通過后，獲取AK\SK。密鑰信息綁定應(yīng)用申請(qǐng)信息，僅限該應(yīng)用申請(qǐng)?jiān)摲?wù)使用。

F.2生成簽名

在調(diào)用服務(wù)之前，先生成簽名，將SK、服務(wù)鏈接與請(qǐng)求參數(shù)替換后，生成當(dāng)次請(qǐng)求參數(shù)的簽名摘要。

F.3請(qǐng)求方法

服務(wù)請(qǐng)求方法包括新增、刪除等，見表F.1。

表F.1請(qǐng)求方法

方法名稱含義

HEAD用于數(shù)據(jù)類（如結(jié)構(gòu)化數(shù)據(jù)和非結(jié)構(gòu)化數(shù)據(jù)）請(qǐng)求的元數(shù)據(jù)獲取

GET用于查詢操作，不應(yīng)產(chǎn)生數(shù)據(jù)的修改或變更

PUT用于新增操作

PATCH用于更新操作

DELETE用于刪除操作

POST用于控制操作以及有安全請(qǐng)求需要的操作

F.4發(fā)起訪問

發(fā)起訪問應(yīng)先通過請(qǐng)求報(bào)文，將請(qǐng)求參數(shù)傳送給服務(wù)網(wǎng)關(guān)，參數(shù)取值范圍不能超過已申請(qǐng)的應(yīng)用訪

問權(quán)限的數(shù)據(jù)范圍，請(qǐng)求參數(shù)根據(jù)服務(wù)數(shù)據(jù)內(nèi)容而定，以下為示例。

示例：請(qǐng)求報(bào)文

POST/open-service/test-fault56/main/testHTTP/1.1

Host:26:8100

Authorization:data-service-auth-v1/360209779915886592/2019-12-02

16:27:29/1800/c01a70258309032d549e3368d6a6fa127faee40f0d780d856679c7f618762a19

Content-Type:application/json;charset=UTF-8

User-Agent:PostmanRuntime/7.19.0

Accept:*/*

Cache-Control:no-cache

Postman-Token:cfe5f7f3-9f8a-4ba0-9328-0f4274c15715,afd215ee-cef5-4b5c-a321-5686f7f6a70e

Host:26:8100

Accept-Encoding:gzip,deflate

Content-Length:6

Connection:keep-alive

cache-control:no-cache

{

"SFDM":"04",

"BBNY":"201908"

15

T/CESXXX—2023

}

F.5返回?cái)?shù)據(jù)

訪問請(qǐng)求在鑒權(quán)通過后，平臺(tái)將服務(wù)響應(yīng)的數(shù)據(jù)以報(bào)文傳回，以下響應(yīng)報(bào)文為示例。

示例：響應(yīng)報(bào)文

HTTP/1.1200OK

Date:Sat,31Dec200523:59:59GMT

Content-Type:application/json;charset=UTF-8

Content-Length:122

{

"msg":"success",

"code":200,

"obj":[

{

"org_id":"3401450105",

"stat_date":"201908",

"gen_mtd":9574.1,

"org_name":"xx電網(wǎng)公司",

"gen_ytd":72441.1,

"power_type":"風(fēng)電",

"update_date":"2019-01-1514:01:13"

},

}

F.6訪問失敗處理

根據(jù)表F.2響應(yīng)狀態(tài)碼說明，判斷訪問失敗的原因，進(jìn)行相應(yīng)的處理。

表F.2響應(yīng)狀態(tài)碼以及說明

響應(yīng)狀態(tài)碼說明

200請(qǐng)求處理正常

400非法請(qǐng)求

401認(rèn)證失敗

402未登錄

403用戶被黑名單限制

406賬號(hào)權(quán)限不足

410簽名time為空或格式錯(cuò)誤！

411請(qǐng)求簽名已過期！

412請(qǐng)求不在AK指定的IP發(fā)起！

413AK不存在！

414簽名認(rèn)證失??！

415參數(shù)不在授權(quán)范圍！

416該服務(wù)禁止訪問！