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

面向統(tǒng)一電力數(shù)據(jù)中心的應用開發(fā)技術規(guī)范目 次前言 II范圍 1規(guī)范性引用文件 1術語和定義 1縮略語 2總則 2通訊協(xié)議 4數(shù)據(jù)訪問方法 5訪問安全 6附錄A（規(guī)范性）編碼設置 8附錄B（規(guī)范性）接口邏輯 10附錄C（規(guī)范性）接口返回體 12附錄D（規(guī)范性）程序異常處理操作 13附錄E（規(guī)范性）程序打包 14附錄F（規(guī)范性）服務調(diào)用過程 15附錄G（資料性）數(shù)據(jù)服務接口運行維護 18參考文獻 19IPAGEPAGE19面向統(tǒng)一電力數(shù)據(jù)中心的應用開發(fā)技術規(guī)范范圍規(guī)范性引用文件（包括所有的修改單適用于本文件。GB/T22239信息安全技術網(wǎng)絡安全等級保護基本要求GB35114公共安全視頻監(jiān)控聯(lián)網(wǎng)信息安全技術要求DL/T2424智能電網(wǎng)術語術語和定義DL/T2424界定的以及下列術語和定義適用于本文件。3.1電力數(shù)據(jù)powerdata在發(fā)、輸、變、配、用等各環(huán)節(jié)所采集、加工與分析而取得的電力相關業(yè)務數(shù)據(jù)集合。3.2電力數(shù)據(jù)中心powerdatacenter電力IT架構的底層基礎設施，具備數(shù)據(jù)統(tǒng)一存儲、計算、分析和服務四大功能，提供海量數(shù)據(jù)存儲3.3接入access3.4接口interface系統(tǒng)與另一個系統(tǒng)之間的公共邊界，信息通過該公共邊界傳遞。3.5數(shù)據(jù)模型datamodel覆蓋資產(chǎn)、營銷、人資、財務、綜合等業(yè)務領域的數(shù)據(jù)集合，由概念模型、邏輯模型、物理模型等組成。3.6服務接口serviceinterface特定功能的形式化描述，定義了實現(xiàn)功能所需的參數(shù)和返回結果。3.7服務調(diào)用者serviceconsumer根據(jù)服務接口描述訪問服務的程序。3.8服務提供者serviceprovider實行服務接口定義的功能并提供服務的程序。縮略語以下縮略語適用于本文件。API：應用編程接口（ApplicationProgrammingInterface）AK/SK：訪問密鑰（AccessKey/SecretAccessKey）CPU：中央處理器（CentralProcessingUnit）HTTP：超文本傳輸協(xié)議（HyperTextTransferProtocol）HTTPS：超文本傳輸安全協(xié)議（HyperTextTransferProtocolOverSecureSocketLayer）IP：網(wǎng)際互連協(xié)議（InternetProtocol）IT：互聯(lián)網(wǎng)技術（InternetTechnology）JSON：JavaScript對象標記（JavaScriptObjectNotation）MTBF：平均故障間隔時間（MeanTimebetweenFailures）MTTR：最長修理時間（MaximumTimeToRepair）PC：個人計算機（PersonalComputer）TPS：并發(fā)數(shù)（TransactionsPerSecond）VPN：虛擬專用網(wǎng)絡（VirtualPrivateNetwork）REST：表述性狀態(tài)轉移（RepresentationalStateTransfer）RESTFUL：一種網(wǎng)絡應用程序的設計風格和開發(fā)方式（RepresentationalStateTransfer）SOAP：簡單對象訪問協(xié)議（SimpleObjectAccessProtocol）TCP：傳輸控制協(xié)議（TransmissionControlProtocol）URI：統(tǒng)一資源標識符（UniformResourceIdentifier）URL：統(tǒng)一資源定位符（UniformResourceLocator）UTF-8：針對Unicode的可變長度字符編碼（8-bitUnicodeTransformationFormat）WSDL：Web服務描述語言（WebServicesDescriptionLanguage）XML：可擴展標記語言（ExtensibleMarkupLanguage）總則概述數(shù)據(jù)應用系統(tǒng)通過統(tǒng)一的APIPCWEB圖1電力數(shù)據(jù)中心的數(shù)據(jù)應用系統(tǒng)功能架構示意圖數(shù)據(jù)服務接口需求和設計數(shù)據(jù)服務接口需求由數(shù)據(jù)服務調(diào)用者或數(shù)據(jù)服務提供者提出，具體應滿足：數(shù)據(jù)服務調(diào)用者評估使用需求，對暫無相應數(shù)據(jù)服務接口的數(shù)據(jù)集提出服務接口生成需求；數(shù)據(jù)服務提供者進行需求調(diào)研，對有使用需求或有較高使用價值的數(shù)據(jù)集提出服務接口生成需求；數(shù)據(jù)歸口管理部門對數(shù)據(jù)服務接口生成需求進行審核。G，數(shù)據(jù)服務接口設計應遵循以下要求：以業(yè)務應用需求為驅動，按需進行服務的生成，遵循企業(yè)級服務沉淀共享原則，避免重復生成同一類型、同一性質的服務接口；按照電力數(shù)據(jù)中心數(shù)據(jù)存儲分層架構設計，基于共享層、分析層數(shù)據(jù)進行數(shù)據(jù)服務接口生成，不宜基于貼源層生成服務接口；按照數(shù)據(jù)分級權限進行數(shù)據(jù)服務接口訪問控制，根據(jù)數(shù)據(jù)業(yè)務特點及應用特點設置服務接口的有效期約束。服務注冊A～E。用戶通過上傳程序包、填寫服務使用規(guī)則等信息進行服務注冊申請，步驟應滿足：上傳程序包：上傳注冊至系統(tǒng)的服務程序包；服務接口參數(shù)：系統(tǒng)解析出來程序包中的服務請求參數(shù)和響應參數(shù)；服務基本信息：服務基本信息填寫表單；完成：成功提交服務注冊申請，進入審批。數(shù)據(jù)服務接口發(fā)布應基于數(shù)據(jù)中臺數(shù)據(jù)服務組件完成，包括操作請求和返回應答兩部分。數(shù)據(jù)1表1數(shù)據(jù)服務接口發(fā)布請求參數(shù)序號名稱說明1發(fā)布請求參數(shù)APINameAPI本號四部分組成2StageName運行環(huán)境名稱，取值為生產(chǎn)環(huán)境或測試環(huán)境3Description授權說明4發(fā)布返回參數(shù)RequestId請求唯一標識數(shù)據(jù)服務接口查看應基于數(shù)據(jù)中臺數(shù)據(jù)服務組件完成，包括操作請求和返回應答兩部分。數(shù)據(jù)2表2數(shù)據(jù)服務接口查看請求參數(shù)序號名稱說明1查看請求參數(shù)APIId指定的API編號2APINameAPI名稱（模糊匹配）3StageName運行環(huán)境名稱，取值為生產(chǎn)環(huán)境或測試環(huán)境4PageSize指定分頁查詢時每頁行數(shù)5PageNumber指定要查詢的頁碼6查看返回參數(shù)RequestId本次請求編號7TotalCount返回結果的總條數(shù)8PageNumber返回指定的頁碼9PageSize返回指定的每頁條數(shù)通訊協(xié)議協(xié)議格式服務接口集成以WebService和RESTService為載體，相關協(xié)議要求見表3。表3WebService和RESTService協(xié)議棧項目協(xié)議WebService協(xié)議棧服務發(fā)現(xiàn)層UDDI服務描述層WSDL消息封裝層SOAP服務傳輸層HTTP、HTTPSRESTService協(xié)議棧服務發(fā)現(xiàn)層無服務描述層URI消息封裝層JSON服務傳輸層HTTP、HTTPS數(shù)據(jù)格式WebServiceXMLRESTServiceJSONURLURL全部采用小寫字母及數(shù)字，至少兩層，根據(jù)場景支持多級分類。URL定義規(guī)則如下，說明見表4：{通信協(xié)議}//{數(shù)據(jù)服務網(wǎng)關地址}/{服務所屬應用域}/{版本號}/{子目錄}/…/{子目錄}表4資源標識元素序號元素名稱說明1通信協(xié)議服務接口與調(diào)用請求之間的通信協(xié)議，使用HTTP或HTTPS的一種2數(shù)據(jù)服務網(wǎng)關地址數(shù)據(jù)服務網(wǎng)關IP地址或域名3服務所屬應用域根據(jù)業(yè)務部門使用場景簡稱劃分4版本號服務接口的版本信息，如V1.0.05子目錄法，即第一個單詞為小寫，隨后的單詞第一個字符大寫數(shù)據(jù)訪問方法數(shù)據(jù)訪問流程API接口及第三方接口的注冊；服務調(diào)用者通過數(shù)據(jù)服務組件查詢數(shù)據(jù)服務接口定義信息；服務調(diào)用者獲取數(shù)據(jù)服務接口定義信息；服務調(diào)用者向數(shù)據(jù)服務組件發(fā)起數(shù)據(jù)服務接口請求，數(shù)據(jù)服務組件 請求進行鑒權、路由處理，并將請求轉發(fā)到相關組件或第三方接口；服務提供者接收數(shù)據(jù)服務接口請求；服務提供者對請求進行處理，并返回數(shù)據(jù)服務接口應答信息至數(shù)據(jù)服務組件，由數(shù)據(jù)服務組件對響應進行路由、轉換等處理，并轉發(fā)到服務調(diào)用者；服務調(diào)用者接收數(shù)據(jù)服務接口應答結果。服務申請RESTFULAPI進行服務申請時，應先進行應用信息登記，登記應遵循以下規(guī)范：——應用名稱：遵循應用名稱命名規(guī)范進行命名；——應用IP：為應用部署IP，應真實、有效；——應用用途：為字符串，不做限制，長度為5～50個字符。申請用途應基于真實數(shù)據(jù)服務需求進行申請說明，不應編造。服務調(diào)用網(wǎng)絡策略數(shù)據(jù)消費應用在正式調(diào)用前，數(shù)據(jù)消費應用到數(shù)據(jù)服務引擎間的網(wǎng)絡能正常訪問：a）b）子單位數(shù)據(jù)消費應用需在網(wǎng)側及子單位側均申請網(wǎng)絡策略。調(diào)用程序服務申請審核通過后，通過獲取的密鑰信息，進行服務調(diào)用，詳見附錄F。鑒權服務消費者訪問數(shù)據(jù)時，訪問權限和數(shù)據(jù)范圍都因應用不同而不同，數(shù)據(jù)服務引擎應確認到每次訪問的應用信息，包括應用信息、服務的訪問權限、權限數(shù)據(jù)范圍等，應滿足：a）應用部署IP與應用登記的應用IP一致，否則將無法訪問；b）調(diào)用數(shù)據(jù)在訪問權限數(shù)據(jù)范圍內(nèi)，否則無法正常訪問?；跀?shù)據(jù)服務引擎給的訪問密鑰，AccessKeySecretAccessKeySK訪問安全基本要求GB/T22239、GB35114應采用安全等級認證機制。應采用加密技術，實施賬號權限分配管理。系統(tǒng)安全應及時安裝補丁，補丁安裝前應進行離線測試。應進行安全加固，關閉暫不使用的服務，設置關鍵配置文件的訪問權限，開啟日志審計功能。24h，漏洞應及時進行處理，容器應進行加密處理。應支持對物聯(lián)網(wǎng)網(wǎng)關軟件包、補丁包、容器、APP網(wǎng)絡安全網(wǎng)絡安全應滿足如下要求：傳輸安全：數(shù)據(jù)傳輸采用電力通信專網(wǎng)（光纖、非網(wǎng)絡專線等有線通信）方式時，生產(chǎn)控制大區(qū)的終端滿足縱向加密認證接入要求，管理信息大區(qū)的終端通過訪問控制措施滿足邊界防護要求；數(shù)據(jù)傳輸采用運營商公網(wǎng)（有線或無線通信）或因特網(wǎng)時，根據(jù)數(shù)據(jù)所接入的安全分區(qū)采用相應的安全防護措施；VPN接入安全：通過有線（電力專線）、無線（自建無線網(wǎng)絡或公網(wǎng)無線網(wǎng)絡）接入現(xiàn)場網(wǎng)關（終端）的節(jié)點，宜接入不同的設備；電力專線與無線公網(wǎng)數(shù)據(jù)不應混合接入傳輸。c）ID具備內(nèi)嵌式或外接式的安全功能硬件；具備身份鑒權認證方式，身份鑒權認證方式符合電力數(shù)據(jù)中心的數(shù)據(jù)應用系統(tǒng)接入鑒權要求；采用符合國密的密碼算法；URL接口安全應滿足以下要求：對于涉密數(shù)據(jù)，進行脫敏處理或者特殊加密；6數(shù)據(jù)服務訪問權限按照數(shù)據(jù)分級、分類權限等級管理要求進行授權管理。應滿足：數(shù)據(jù)服務接口授權：根據(jù)數(shù)據(jù)服務調(diào)用者申請的數(shù)據(jù)服務權限，進行審核及授權。數(shù)據(jù)服務接口授權應基于數(shù)據(jù)中臺數(shù)據(jù)服務組件完成，包括操作請求和返回應答兩部分，示5；表5數(shù)據(jù)服務接口授權參數(shù)示例序號名稱說明1請求參數(shù)ApiIdApi唯一標識編號，由系統(tǒng)生成2StageName運行環(huán)境名稱，取值為生產(chǎn)環(huán)境或測試環(huán)境3AppId指定要執(zhí)行授權操作的APP編號4Description授權說明5返回參數(shù)RequestId請求唯一標識6。表6服務接口認證方式序號認證方式說明1APPKey認證通過AppKey和AppSecret進行簽名認證2Basic認證采用HTTP的BASIC認證方式，后端服務通過用戶名和密碼進行認證3PublicKey認證采用AuthAdv的TokenNE認證，后端服務通過公鑰驗證Token進行認證4其他認證可直接調(diào)用API，無需認證，部分公開性信息，僅查詢類的接口可采用該方式附錄 A（規(guī)范性）編碼設置模板程序目錄數(shù)據(jù)服務接口模板程序的目錄結構應包含公共常量、控制層、異常處理、日志記錄、實體類、業(yè)務處理。各數(shù)據(jù)服務開發(fā)人員在開發(fā)過程中需將相應功能的代碼對號存放，不隨意刪減模板程序中的目錄、代碼。公共配置數(shù)據(jù)服務引擎當前推薦使用YAML示例1：注冊中心地址:eureka:client:healthcheck:enabledserviceUrl:defaultZone: 26:8061/eureka/ ， 27:8061/eureka/ 36:8061/eureka/示例2：程序訪問端號及訪問路徑：server:port:8080context-path:/3：management:security:enabled:falseendpoints:web:exposure:include:"*"自定義配置數(shù)據(jù)庫代碼見示例。示例：數(shù)據(jù)庫：spring:datasource:driver-class-name:com.mysql.jdbc.Driverurl:jdbc:mysql://ip:port/database_name?characterEncoding=UTF-8&useSSL=falseusername:rootpassword:在編碼過程中，應將IDE中的字符編碼設置成UTF-8編碼程序命名。命名規(guī)范代碼中的命名均不能以下劃線或美元符號開始，也不能以下劃線或美元符號結束。示例：反例：_name/name/$name/name_/name$/name代碼中的命名嚴禁使用拼音與英文混合的方式，更不可直接使用中文的方式。示例1：正例：beijing/guangzhou等國際通用的名稱，可視同英文。示例2：反例：CheXiaoOption[撤銷]/getfazhiByName（）[閥值]/int某變量=3類名使用UpperCamelCaseDO/BO/DTO/VO/AO/PO/UID1：正例：MarcoPolo/UserDO/XmlService/TcpUdpDeal/TaPromotion2：反例：macroPolo/UserDo/XMLService/TCPUDPDeal/TAPromotionlowerCamelCase示例：正例：localValue/getHttpMessage（）/inputUserId常量命名全部大寫，單詞間用下劃線隔開，力求語義表達完整清楚，不要嫌名字長。示例1：正例：MAX_STOCK_COUNT示例2：反例：MAX_COUNT抽象類命名使用Abstract或BaseException類型與中括號緊挨相連來表示數(shù)組。1：intarrayDemo;示例2：反例：在main參數(shù)中，使用Stringargs[]來定義。POJOis示例：BooleanisDeletedisDeleted（），RPCdeleted，導致屬性獲取不到，進而拋出異常。示例：com.csg.dse.srvc.utilspring）杜絕完全不規(guī)范的縮寫，避免望文不知義。示例：反例：AbstractClass“縮寫”命名成AbsClass；condition“縮寫”命名成condi。數(shù)據(jù)服務名稱命名用于能夠容易的識別、檢索出某一服務，應遵循：3～27Jar3～1550，為服務顯示的名稱，可重復。應用名稱命名為字符串，限制中文、英文、數(shù)字及下劃線，長度在5～15個字符，為應用顯示的名稱，可重復；系統(tǒng)生成應用ID，為應用的唯一標識。系統(tǒng)間交互的數(shù)據(jù)編碼格式宜采用UTF-8字符集進行編碼。附錄 B（規(guī)范性）接口邏輯概述控制器RESTAPI（Controller）cloud——Controllerorg.springframework.web.bind.annotation聲明控制類，可使用@RequestMappinp——使用@PostMapping聲明接口請求方式，接口只支持post請求方式；——Controller類應繼承BaseController；——使用@RequestBody聲明請求參數(shù)示例：@RequestMapping（"/Student"）publicclassStudentControllerextendsBaseController{@ResponseBody@PostMapping（"/stuInfo"）publicStudentReturnViewstuInfo（@RequestBodyMyInputViewinputView）{StudentReturnViewview=newStudentReturnView（）;view.setAge（String.valueOf（inputView.getAge（）））;view.setName（inputView.getName（））;returnview;}}注：服務只支持可定義一個controller，controller里只能定義一個接口。接口參數(shù)基于電力數(shù)據(jù)中心提供的模板程序定義數(shù)據(jù)服務接口時，接口參數(shù)部份需定義成一個VO類繼承基類InputView，按要求使用統(tǒng)一的注解進行標注，用到的注解及注意事項如下：——參數(shù)以post方式提供；——接口入?yún)远xbean繼承InputView，并使用@RequestBody傳入?yún)?shù)；——自定義bean的屬性只支持基礎數(shù)據(jù)類型；——應添加@ApiModelProperty對自定義的參數(shù)bean里面的屬性進行描述，應包含：name：字段名；dataType：參數(shù)類型（與方法傳參類型對應）；required：是否應填；value：字段描述；example（示例）。示例：@ResponseBody@PostMapping（"/stuInfo"）publicStudentReturnViewsutInfo（@RequestBodyStuInputViewinputView）{StudentReturnViewview=newStudentReturnView（）;view.setAge（inputView.getAge（））;view.setName（inputView.getName（））;returnview;}@DatapublicclassStudentInputViewextendsInputView{@ApiModelProperty（value="名稱"，name="name"，example="李明"，required=true）privateStringname;@ApiModelProperty（value="年齡"，name="age"，example="1"，required=true）privateStringage;附錄 C（規(guī)范性）接口返回體數(shù)據(jù)服務接口不可直接返回基礎數(shù)據(jù)類型，需統(tǒng)一返回自定義beanbeanBean@ApiModelProperty——value:字段描述；——name：字段名；——example：示例；——required：是否一定有值。cod狀態(tài)碼msg消息vieObjct。示例：publicclassStudentReturnViewextendsReturnView{@ApiModelProperty（value="學生ID"，name="stuId"，example="1"，required=true）privateStringstuId;@ApiModelProperty（value="學生名稱"，name="name"，example="小林"，required=true）privateStringname;@ApiModelProperty（value="學生年齡"，name="age"，example="19"，required=true）privateStringage;@ApiModelProperty（value="學生各分數(shù)詳情"，name="scores"，example="{\"wuli\":90，\"yuwen\":100}"，required=true）privateList<Score>scores;@ApiModelProperty（value="學生總分數(shù)"，name="score"，example="100"，required=true）privateScorescore;附錄 D（規(guī)范性）程序異常處理操作服務發(fā)生系統(tǒng)錯誤進程停止后，容器會對該服務副本進行自動重啟，程序不應對系統(tǒng)錯誤進行處理。異常不要用來做流程控制，條件控制，因為異常的處理效率比條件分支低。catchtrycatchfinallytry-catch。注：如果JDK7及以上，可以使用try-with-resources方式。finallyreturn，finallyreturntryreturn捕獲異常與拋異常，應完全匹配，或者捕獲異常是拋異常的父類。nullnullNPE附錄 E（規(guī)范性）程序打包運行環(huán)境數(shù)據(jù)服務引擎當前系統(tǒng)支持JRE1.8運行環(huán)境，程序打包過程中請將jar包的運行環(huán)境設置成JRE1.8。打包指令基于模板程序開發(fā)的數(shù)據(jù)服務接口程序通過MAVEN進行打包，通過執(zhí)行mvnpackage命令完成打包。程序包命名程序mavntaretdsesrv-teplae-x（.ja，可在pomxml文件自定義文件名及修改版本號。接口描述文件目錄MAVEN打完包后會在JAR包的相應目錄中生成接口描述文件，如未正確生成此文件，將會無法在服務引擎中正常注冊，開發(fā)過程中應遵守接口邏輯規(guī)范。附錄 F（規(guī)范性）AK/SK服務申請審核通過后，獲取AK\SK。密鑰信息綁定應用申請信息，僅限該應用申請該服務使用。生成簽名SK請求方法服務請求方法包括新增、刪除等，見表F.1。表F.1請求方法方法名稱含義HEAD用于數(shù)據(jù)類（如結構化數(shù)據(jù)和非結構化數(shù)據(jù)）請求的元數(shù)據(jù)獲取GET用于查詢操作，不應產(chǎn)生數(shù)據(jù)的修改或變更PUT用于新增操作PATCH用于更新操作DELETE用于刪除操作POST用于控制操作以及有安全請求需要的操作發(fā)起訪問示例：請求報文POST/open-service/test-fault56/main/testHTTP/1.1Host:26:8100Authorization:data-service-auth-v1/360209779915886592/2019-12-0216:27:29/1800/c01a70258309032d549e3368d6a6fa127faee40f0d780d856679c7f618762a19Content-Type:application/json;charset=UTF-8User-Agent:PostmanRuntime/7.19.0Accept:*/*Cache-Control:no-cachePostman-Token:cfe5f7f3-9f8a-4ba0-9328-0f4274c15715,afd215ee-cef5-4b5c-a321-5686f7f6a70eHost:26:8100Accept-Encoding:gzip,deflateContent-Length:6Connection:keep-alivecache-control:no-cache{"SFDM":"04","BBNY":"201908"}返回數(shù)據(jù)訪問請求在鑒權通過后，平臺將服務響應的數(shù)據(jù)以報文傳回，以下響應報文為示例。示例：響應報文HTTP/1.1200OKDate:Sat,31Dec200523:59:59GMTContent-Type:application/json;charset=UTF-8Content-Length:122{"msg":"success","code":200,"obj":[{"org_id":"3401450105","stat_date