标签:
1. 效果演示
//创建服务器 var __服务端 = FT通用访问工厂.创建服务端(); __服务端.端口 = 8888; __服务端.开启(); //实际对象 var __基本状态 = new M基本状态(); __基本状态.版本 = "1.0.0.0"; __基本状态.待处理问题.Add(new M问题 { 等级 = E重要性.普通, 内容 = "xxxx" }); __基本状态.待处理问题.Add(new M问题 { 等级 = E重要性.重要, 内容 = "yyyy" }); __基本状态.开启时间 = DateTime.Now; __基本状态.连接设备.Add(new M设备连接 { IP = IPAddress.Parse("192.168.0.1"), 标识 = "X1", 类型 = "X", 连接中 = true }); __基本状态.连接设备.Add(new M设备连接 { IP = IPAddress.Parse("192.168.0.2"), 标识 = "Y1", 类型 = "Y", 连接中 = true }); __基本状态.位置 = "威尼斯"; __基本状态.业务状态 = new Dictionary<string, string> { { "参数1", "参数1值" }, { "参数2", "参数2值" } }; //可通信对象 var __对象 = new M对象("基本状态", ""); __对象.添加属性("版本", () => __基本状态.版本, E角色.所有, null);//最后一个参数是元数据定义 __对象.添加属性("位置", () => __基本状态.位置, E角色.所有, null); __对象.添加属性("开启时间", () => __基本状态.开启时间.ToString(), E角色.所有, null); __对象.添加属性("待处理问题", () => HJSON.序列化(__基本状态.待处理问题), E角色.所有, null); __对象.添加属性("连接设备", () => HJSON.序列化(__基本状态.连接设备), E角色.所有, null); __对象.添加属性("业务状态", () => HJSON.序列化(__基本状态.业务状态), E角色.所有, null); __对象.添加方法("重启", __实参 => { //处理实参 return string.Empty; //返回空字符串或者json格式的对象 }, E角色.所有, null, null); //最后两个参数是对参数和返回值的元数据定义 __对象.添加事件("发生了重要变化", E角色.所有, null); //将对象加入到服务器 __服务端.添加对象("基本状态", () => __对象); //触发服务器端事件 __服务端.触发事件("基本状态", "发生了重要变化", null, null);//最后两个参数是实参和客户端地址列表(可选)
//创建客户端 var __客户端 = FT通用访问工厂.创建客户端(); __客户端.连接(new IPEndPoint(IPAddress.Any, 8888)); var __版本 = __客户端.查询属性值("基本状态", "版本"); var __待处理问题 = HJSON.反序列化<List<M问题>>(__客户端.查询属性值("基本状态", "待处理问题")); __客户端.执行方法("基本状态", "重启", null); //最后一个参数是实参 __客户端.订阅事件("基本状态", "发生了重要变化", __实参 => { //处理实参 });
字段 |
类型 |
长度(字节) |
说明 |
起始标识 |
Byte[] |
2 |
固定为0xAAAA,用于识别报文开始 |
报文内容长度 |
Int32 |
4 |
余下所有字段长度 |
功能标识 |
Int16 |
2 |
用于识别报文类型 |
发送方事务标识 |
Int32 |
4 |
由发送方指定。当会话类型为请求型时,用于区别发送方的不同请求;当会话类型为通知型时,固定为0。 |
接收方事务标识 |
Int32 |
4 |
由接收方指定。当会话类型为请求型时,用于区别接收方的不同请求,特别的,会话开始的第一条报文,发送方的该字段填0;当会话类型为通知型时,固定为0。 |
负载 |
Byte[] |
* |
由报文内容长度字段指定, 推荐编码格式为UTF8文本, 采用json格式, 大数据量时采用压缩算法 |
功能 |
码 |
查询对象列表(请求) |
1 |
查询对象列表(响应) |
2 |
查询对象明细(请求) |
3 |
查询对象明细(响应) |
4 |
执行方法(请求) |
5 |
执行方法(响应) |
6 |
查询属性值(请求) |
7 |
查询属性值(响应) |
8 |
订阅事件 |
9 |
取消订阅事件 |
A |
接收事件 |
B |
查询对象列表
请求: 无
响应: [{名称, 分类, 角色}]
查询对象明细
请求: {对象名称}
响应: {属性列表[{名称, 元数据, 角色}], 方法列表[{名称, 形参列表[{名称, 元数据}, 角色], 返回值元数据}], 事件列表[{名称, 形参列表[{名称, 元数据}], 角色}]}
元数据: {类型, 结构(单值/对象/单值数组/对象数组), 描述, 默认值, 范围, 子成员列表[{名称, 元数据}]}
执行方法
请求: {对象名称, 方法名称, 实参列表[{名称, 值}]}
响应: {成功, 描述, 返回值}
查询属性值
请求: {对象名称, 属性名称}
响应: {成功, 描述, 返回值}
订阅事件
通知: {对象名称, 事件名称}
取消订阅事件
通知: {对象名称, 事件名称}
接收事件
通知: {对象名称, 事件名称, 实参列表[{名称, 值}]}
响应数据格式(ContentType)为application/json;charset=utf-8
功能 |
HTTP方法 |
地址 |
查询对象列表 |
GET/ POST |
objects.k |
查询对象明细 |
GET/ POST |
object.k |
执行对象方法 |
GET/ POST |
method.k |
查询对象属性值 |
GET/ POST |
proterty.k |
登录 |
POST |
login.k |
心跳 |
GET |
heart.k |
注:成功后会设置cookies, 键为token
查询对象列表
参数: 无
响应: [{名称, 分类, 角色}]
查询对象明细
参数: 对象名称
响应: {属性列表[{名称, 元数据, 角色}], 方法列表[{名称, 形参列表[{名称, 元数据}], 返回值元数据, 角色}]}
执行方法
参数: 对象名称, 方法名称, 实参列表[{名称, 值}]
响应: {成功, 描述, 返回值}
查询对象属性值
参数: 对象名称, 属性名称
响应: {成功, 描述, 返回值}
登录
参数: password
响应: {成功(true/false), 描述}
心跳
参数: 无
响应: 服务器时间
public interface IT服务端 { int 端口 { get; set; } int WebApi端口 { get; set; } void 添加对象(string 对象名称, Func<M对象> 获取对象); void 删除对象(string 对象名称); void 开启(); event Action<IPEndPoint> 客户端已连接; event Action<IPEndPoint> 客户端已断开; List<IPEndPoint> 客户端列表 { get; } void 关闭(); void 触发事件(string 对象名, string 事件名, Dictionary<string, string> 实参 = null, List<IPEndPoint> 地址列表 = null); } public interface IT客户端 { IPEndPoint 设备地址 { get; } void 连接(IPEndPoint 设备地址); void 断开(); bool 连接正常 { get; } /// <summary> /// true:主动断开,false:被动断开 /// </summary> event Action<bool> 已断开; bool 自动重连 { get; set; } event Action 已连接; M对象列表查询结果 查询可访问对象(); M对象明细查询结果 查询对象明细(string 对象名称); string 查询属性值(string 对象名, string 属性名, int 超时毫秒 = 3000); string 执行方法(string 对象名, string 方法名, Dictionary<string,string> 参数列表 = null, int 超时毫秒 = 3000); void 订阅事件(string 对象名, string 事件名, Action<Dictionary<string, string>> 处理方法); void 注销事件(string 对象名, string 事件名, Action<Dictionary<string, string>> 处理方法); /// <summary> /// 通常用于调试 /// </summary> event Action<M接收事件> 收到了事件; } public class M对象 { public string 名称 { get { return 概要.名称; } set { 概要.名称 = value; } } public string 分类 { get { return 概要.分类; } set { 概要.分类 = value; } } public E角色 角色 { get { return 概要.角色; } set { 概要.角色 = value; } } internal M对象概要 概要 { get; set; } internal M对象明细查询结果 明细 { get; set; } /// <summary> /// 字典中的键string:方法名; 值:方法; 方法中的string:返回值 /// </summary> Dictionary<string, Func<Dictionary<string, string>, string>> _所有方法 = new Dictionary<string, Func<Dictionary<string, string>, string>>(); /// <summary> /// 字典中的键string:方法名; 值:方法; 方法中的string:返回值 /// </summary> Dictionary<string, Func<Dictionary<string, string>, IPEndPoint, string>> _所有方法_带地址 = new Dictionary<string, Func<Dictionary<string, string>, IPEndPoint, string>>(); /// <summary> /// 字典中的键string:属性名; 值:属性值计算方法 /// </summary> Dictionary<string, Func<string>> _所有属性方法 = new Dictionary<string, Func<string>>(); public M对象(string __名称, string __分类) { this.概要 = new M对象概要(__名称, __分类); this.明细 = new M对象明细查询结果(); } public void 添加属性(string __名称, Func<string> __计算值, E角色 __角色 = E角色.开发, M元数据 __元数据 = null) { this.角色 = this.角色 | __角色; this.明细.属性列表.Add(new M属性(__名称, __元数据, __角色)); _所有属性方法[__名称] = __计算值; } public void 添加方法(string __名称, Func<Dictionary<string, string>, string> __执行方法, E角色 __角色 = E角色.开发, List<M形参> __参数列表 = null, M元数据 __返回值元数据 = null) { this.角色 = this.角色 | __角色; _所有方法[__名称] = __执行方法; this.明细.方法列表.Add(new M方法(__名称, __参数列表, __返回值元数据, __角色)); } public void 添加方法(string __名称, Func<Dictionary<string, string>, IPEndPoint, string> __执行方法, E角色 __角色 = E角色.开发, List<M形参> __参数列表 = null, M元数据 __返回值元数据 = null) { this.角色 = this.角色 | __角色; _所有方法_带地址[__名称] = __执行方法; this.明细.方法列表.Add(new M方法(__名称, __参数列表, __返回值元数据, __角色)); } internal string 执行方法(string __名称, Dictionary<string, string> __参数列表, IPEndPoint __来源) { if (_所有方法.ContainsKey(__名称)) { return _所有方法[__名称].Invoke(__参数列表); } if (_所有方法_带地址.ContainsKey(__名称)) { return _所有方法_带地址[__名称].Invoke(__参数列表, __来源); } throw new ApplicationException("执行方法失败: 无此方法"); } internal string 计算属性(string __属性名称) { if (_所有属性方法.ContainsKey(__属性名称)) { return _所有属性方法[__属性名称](); } throw new ApplicationException("计算属性失败: 无此属性"); } public void 添加事件(string __名称, E角色 __角色 = E角色.开发, List<M形参> __参数列表 = null) { this.角色 = this.角色 | __角色; this.明细.事件列表.Add(new M事件(__名称, __参数列表, __角色)); } }
名片
属性
名称描述版本号版本时间
方法
查询返回值: {名称, 描述, 版本号, 版本时间}查询参数返回值: [{名称, 值}]
状态
属性
启动时间未清除告警数量健康状态(优/良/中/差)状态开始时间注: 健康状态推荐规则是存在紧急告警为差, 存在重要告警为中, 存在次要告警为良, 否则为优
方法
查询概要状态返回值: {启动时间, 健康状态, 状态开始时间, 未清除告警数量}查询业务概要参数: 类别(可为空), 属性(可为空)返回值: [{类别, 属性, 当前值, 正常范围, 正常, 单位, 描述}]查询未清除告警参数: 条件{每页数量, 页数, 来源设备类型(可选), 来源设备标识(可选), 类别(可选), 重要性(可选), 关键字(可选)}返回值: {总数量, 列表[{标识, 来源设备类型, 来源设备标识, 产生时间, 类别, 重要性, 描述, 原因, 解决方案}]}重要性:
一般(1)
正常通知, 无需排除告警
次要(2)
非直接影响业务的使用, 不需要立即处理, 但还是需要排除告警
重要(3)
严重的故障, 可能会影响业务, 需要用户处理
紧急(4)
系统级故障, 严重影响业务, 需要用户立即处理
事件
上报告警参数: 事件参数{标识, 来源设备类型, 来源设备标识, 产生时间, 类别, 重要性, 描述, 原因, 解决方案}上报清除参数: 事件参数{标识, 来源设备类型, 来源设备标识}健康状态变化参数: 事件参数{启动时间, 健康状态, 状态开始时间, 未清除告警数量}
系统
方法
重启返回值: 无关闭返回值: 无查询版本记录返回值: [{版本号, 标签[], 修改记录}]
FTP
属性
支持(true/false)运行中(true/false)端口号目录路径编码(ASCII/UTF8/GB2312)
方法
设置端口号参数: 端口号返回值: 无开启返回值: 无关闭返回值: 无
初衷
公司的界面软件内容非常混杂,充斥了大量的面向开发人员的元素,与其他设备间的协议,太多的地方让人恶心,耦合度极高,稳定性和可维护性极差。年前讨论重构,其中最基本的一条思路就是区别客户、工程、开发三种角色,面向最终客户的界面软件与其他设备间的协议,应该以应用为导向设计协议(上层决定下层,下层提供可行性约束,协议接口必须抽象)。将面向开发人员的内容与面向最终客户的软件分离开后,需要重新编写面向开发人员的界面与协议,加上我之前一直重视和建议面向工程(及测试)人员开发工具类软件,这就是设计通用访问协议的初衷,因为工程和开发人员不需要最终客户那样的定制化的界面。经过反复的推敲,最终以“自描述”为核心的界面以及协议诞生了。
演化
以后设计分布式的软件,首先完全面向业务的设计出需要的对象及其成员元数据,形成一份简单的但是纯粹的协议,无需定义额外的功能码、报文头、结构体;然后服务端基于通用访问SDK(与平台和开发语言相关),注入对象及其成员的实现(类似于和程序内部的模块、对象挂钩子或是牵线),通过通用访问工具可以直接测试协议接口,无需最终的客户端,同时提供一些面向工程和开发人员自身的对象(这部分对象易变性很高,以往常寄生在面向客户的界面软件中,严重加大无谓的工作量),以便部署和调试;客户端方面同样基于通用访问SDK实现访问各种设备的协议约定的对象;最后如果一个设备需要与多个其他类型的设备互联,也无需定义多套功能码、报文编解码方案,只需使用对象来提供统一的服务。似乎看到了蓝天白云,鸟语花香,人人和睦相处,高效自动化工作的画面。
标签:
原文地址:http://www.cnblogs.com/wangk/p/4cfa380ab18cf72eb6d13d25cf7af535.html