接触过非常多电商的WebService，有种一看就蛋疼的设计，今天要从这个反例说一说 WebService 的设计。
[WebMethod]
public string QueryOrderDetail(string xml)
{
...
}
如上代码输入是一个XML，输出也是一个XML，方法内部自己在做序列化和反序列化。放着成熟的SOAP标准不用，自己再实现一套数据标准。
反而XML成为一个黑盒，调用两方不得不依赖于接口文档，真是吃力不讨好。
因此好的WebService接口，应该从以下几个方面细致考虑：
一. 參数
(1) 參数应该直接使用简单的数据类型（POCO、POJO），甚至时间类型都能够考虑用string，仅仅要两方约束好时间字符串的格式。
(2) 假设參数个数超过3个，那就须要考虑设计一个Class了，避免參数列表过长，当然这没有硬性规定。
(3) 设计统一的參数规则。比方对外提供的查询接口就要考虑分页相关的数据。保证相似的接口都有统一的參数定义，形成习惯是提升效率最好方式。
业务參数和非业务參数应该分开，比方分页的数据就能够抽象出基类。
二. 异常
(1) 使用框架中定义的Exception类型，比方：SoapException, FaultException(WCF)。
(2) 尽量避免将异常定义在返回值中，通过返回值定义错误那么不管服务端还是client都要写非常多if ... else 分支。
(3) 系统异常和业务异常要区分好，比方使用 SoapException 能够用 Code 来区分，比方：System.Error 表示系统错误，Bussiness.Error 表示业务错误。
(4) 补充：.net framework 假设没有包装那么默认有两种 fautCode: soap:Client 和 soap:Server。假设client传入BadRequest 基本就是 soap:Client 错误，其它 没有自己定义code的则就是 soap:Server 的错误。
三. 安全
不管何时都要保证系统的安全性，我认为安全也分系统安全和业务安全两种：
(1) 系统安全主要是指client的认证授权，调用次数(须要考虑会不会拖垮业务系统) 等
(2) 业务安全主要是指数据查询/操作权限，当然这个主要是从业务角度考虑的。
四. 日志
日志能够方便排查错误，还能够通过日志来分析服务基本信息（比方：调用次数，失败次数等），必要时还能够通过日志来进行重试。
另外要考虑开发的便捷，设计统一的日志拦截处理。
以 WebService Application (.NET 3.5) 为例，记录几种经常使用的编程技巧。
原始的 WebService 例如以下：
using System;
using System.Collections.Generic;
using System.Linq;
using System.Web;
using System.Web.Services;
using WebService1.Entity;
using WebService1.Service;
using System.Web.Services.Protocols;
namespace WebService1
{
[WebService(Namespace = "http://tempuri.org/")]
[WebServiceBinding(ConformsTo = WsiProfiles.BasicProfile1_1)]
[System.ComponentModel.ToolboxItem(false)]
public class Service1 : System.Web.Services.WebService
{
[WebMethod]
public PageResult<Order> QueryOrder(Query<OrderCondition> queryInfo)
{
OrderService service = new OrderService();
return service.Query(queryInfo);
}
}
}
PageResult<T>, Query<T> 将统一的业务部分抽取出来，这样定义其它的业务对象就能简化了。
using System;
using System.Collections.Generic;
namespace WebService1.Entity
{
[Serializable]
public class PageResult<T>
{
public int PageNo { get; set; }
public int PageSize { get; set; }
public int TotalCount { get; set; }
public int PageCount { get; set; }
public bool HasNextPage { get; set; }
public List<T> Data { get; set; }
}
}
using System;
using System.Collections.Generic;
namespace WebService1.Entity
{
[Serializable]
public class Query<T>
{
public int PageNo { get; set; }
public int PageSize { get; set; }
public T Condition { get; set; }
}
}
跳过业务处理部分，来关注一下应用框架考虑的日志和安全拦截。能够利用 .NET framework 的 Soap Extensions (msdn) 非常easy地实现对 WebMethod 的 AOP。
Soap Extensions 能够通过两种方式“注入”： 自己定义Atrribute 或者通过 Web.config 里的 soapExtensionTypes 进行声明。
TraceExtension 的实现：
using System;
using System.Collections.Generic;
using System.Linq;
using System.Web;
using System.IO;
using System.Web.Services.Protocols;
using log4net;
using System.Xml;
namespace WebService1.Common
{
public class TraceExtension : SoapExtension
{
private ILog logger = LogManager.GetLogger(typeof(TraceExtension));
Stream oldStream;
Stream newStream;
public override System.IO.Stream ChainStream(System.IO.Stream stream)
{
oldStream = stream;
newStream = new MemoryStream();
return newStream;
}
public override void ProcessMessage(SoapMessage message)
{
switch (message.Stage)
{
case SoapMessageStage.BeforeDeserialize:
log4net.ThreadContext.Properties["ip"] = HttpContext.Current.Request.UserHostAddress;
log4net.ThreadContext.Properties["action"] = message.Action;
WriteInput(message);
break;
case SoapMessageStage.AfterDeserialize:
break;
case SoapMessageStage.BeforeSerialize:
break;
case SoapMessageStage.AfterSerialize:
WriteOutput(message);
break;
default:
throw new Exception("Invalid Stage");
}
}
public override object GetInitializer(Type serviceType)
{
return null;
}
public override object GetInitializer(LogicalMethodInfo methodInfo, SoapExtensionAttribute attr)
{
return null;
}
public override void Initialize(object initializer)
{
//filename = (string)initializer;
}
public void WriteOutput(SoapMessage message)
{
string soapString = (message is SoapServerMessage) ? "SoapResponse" : "SoapRequest";
string content = GetContent(newStream);
// 为了Format XML，假设从性能考虑应该去掉此处的处理
if (!string.IsNullOrEmpty(content))
{
XmlDocument xmlDoc = new XmlDocument();
xmlDoc.LoadXml(content);
using (StringWriter sw = new StringWriter())
{
using (XmlTextWriter xtw = new XmlTextWriter(sw))
{
xtw.Formatting = Formatting.Indented;
xmlDoc.WriteTo(xtw);
content = sw.ToString();
}
}
}
logger.Info(soapString + ":\n" + content);
Copy(newStream, oldStream);
}
public void WriteInput(SoapMessage message)
{
Copy(oldStream, newStream);
string soapString = (message is SoapServerMessage) ? "SoapRequest" : "SoapResponse";
string content = GetContent(newStream);
logger.Info(soapString + ":\n" + content);
}
void Copy(Stream from, Stream to)
{
TextReader reader = new StreamReader(from);
TextWriter writer = new StreamWriter(to);
writer.WriteLine(reader.ReadToEnd());
writer.Flush();
}
string GetContent(Stream stream)
{
stream.Position = 0;
TextReader reader = new StreamReader(stream);
string content = reader.ReadToEnd();
stream.Position = 0;
return content;
}
}
}TraceAttribute 实现例如以下：using System;
using System.Web.Services.Protocols;
namespace WebService1.Common
{
[AttributeUsage(AttributeTargets.Method)]
public class TraceAttribute : SoapExtensionAttribute
{
private int priority = 0;
public override Type ExtensionType
{
get { return typeof(TraceExtension); }
}
public override int Priority
{
get { return priority; }
set { priority = value; }
}
}
}
当中 TraceExtension 利用 log4net 来记录调用 WebMethod 的Request 和 Response，还包含 ip 和 Action（Action事实上相应的 WebMethod）
相应的 log4net 配置例如以下：
<log4net>
<appender name="RollingFileAppender" type="log4net.Appender.RollingFileAppender">
<param name="File" value="F:\Programming\VSProject2008\WebServiceSample\WebService1\WebService1\Logs\service.log"/>
<param name="DatePattern" value=".yyyy-MM-dd'.log'" />
<param name="AppendToFile" value="true"/>
<param name="MaxSizeRollBackups" value="10"/>
<param name="MaximumFileSize" value="5MB"/>
<param name="RollingStyle" value="Date"/>
<param name="StaticLogFileName" value="false"/>
<layout type="log4net.Layout.PatternLayout">
<param name="ConversionPattern" value="%d [%t] %-5p [%property{ip}] [%property{action}] - %m%n"/>
</layout>
</appender>
<root>
<level value="DEBUG"/>
<appender-ref ref="RollingFileAppender"/>
</root>
</log4net>
那么 WebMethod 仅仅要加上 [Trace] 特性，就能够开启日志记录功能。
[WebMethod]
[Trace]
public PageResult<Order> QueryOrder(Query<OrderCondition> queryInfo)
{
OrderService service = new OrderService();
return service.Query(queryInfo);
}
输出日志例如以下：
2014-05-25 22:05:02,292 [8] INFO [127.0.0.1] [http://tempuri.org/QueryOrder] - SoapRequest:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:tem="http://tempuri.org/">
<soapenv:Body>
<tem:QueryOrder>
<!--Optional:-->
<tem:queryInfo>
<tem:PageNo>1</tem:PageNo>
<tem:PageSize>1</tem:PageSize>
<!--Optional:-->
<tem:Condition>
<!--Optional:-->
<tem:StartTime>?</tem:StartTime>
<!--Optional:-->
<tem:EndTime>?</tem:EndTime>
<!--Optional:-->
<tem:ShopId>?</tem:ShopId>
<!--Optional:-->
<tem:ProductId>?</tem:ProductId>
</tem:Condition>
</tem:queryInfo>
</tem:QueryOrder>
</soapenv:Body>
</soapenv:Envelope>
2014-05-25 22:05:02,357 [8] INFO [127.0.0.1] [http://tempuri.org/QueryOrder] - SoapResponse:
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<soap:Body>
<QueryOrderResponse xmlns="http://tempuri.org/">
<QueryOrderResult>
<PageNo>1</PageNo>
<PageSize>1</PageSize>
<TotalCount>3</TotalCount>
<PageCount>1</PageCount>
<HasNextPage>false</HasNextPage>
<Data>
<Order>
<Id>1</Id>
<OrderDate>2014-05-25 22:05:02</OrderDate>
<ShopId>SHOP001</ShopId>
<ProductId>PRD001</ProductId>
<Quantity>1</Quantity>
<Price>59</Price>
</Order>
...
</Data>
</QueryOrderResult>
</QueryOrderResponse>
</soap:Body>
</soap:Envelope>
接下来利用 SoapHeader 实现最主要的 Basic Authentication 校验，当然你不想每个 WebMethod 去做相同的Check，相同我们实现一个 Soap Extension。
Authentication (SoapHeader) 的定义：
using System;
using System.Web.Services.Protocols;
namespace WebService1.Common
{
public class Authentication : SoapHeader
{
public string UserName { get; set; }
public string Password { get; set; }
}
}AuthCheckExtension 的实现：在 SoapMessage AfterDeserialize 这个阶段，取出client传的 SoapHeader 验证 UserName 和 Password 在服务端是否存在。假设不存在或者错误则抛出 no auth ! 的错误。
using System;
using System.Collections.Generic;
using System.Linq;
using System.Web;
using System.IO;
using System.Web.Services.Protocols;
using WebService1.Config;
namespace WebService1.Common
{
public class AuthCheckExtension : SoapExtension
{
public override void ProcessMessage(SoapMessage message)
{
if (message.Stage == SoapMessageStage.AfterDeserialize)
{
foreach (SoapHeader header in message.Headers)
{
if (header is Authentication)
{
var authHeader = header as Authentication;
var isValidUser = true;
var users = AuthConfiguration.AuthSettings.Users;
if (users != null && users.Count > 0)
{
isValidUser = users.Any(u => u.UserName == authHeader.UserName && u.Password == authHeader.Password);
}
if (!isValidUser)
throw new BizException("no auth !");
}
}
}
}
public override object GetInitializer(Type serviceType)
{
return null;
}
public override object GetInitializer(LogicalMethodInfo methodInfo, SoapExtensionAttribute attribute)
{
return null;
}
public override void Initialize(object initializer)
{
// 初始化 AuthSettings
AuthConfiguration.Config();
}
}
}然后给 WebMethod 加上 [SoapHeader("Authentication"), AuthCheck] 就OK了。using System;
using System.Collections.Generic;
using System.Web;
using System.Web.Services;
using WebService1.Entity;
using WebService1.Service;
using System.Web.Services.Protocols;
using WebService1.Common;
namespace WebService1
{
[WebService(Namespace = "http://tempuri.org/")]
[WebServiceBinding(ConformsTo = WsiProfiles.BasicProfile1_1)]
[System.ComponentModel.ToolboxItem(false)]
public class Service1 : System.Web.Services.WebService
{
public Authentication Authentication { get; set; }
[WebMethod]
[Trace]
[SoapHeader("Authentication"), AuthCheck]
public PageResult<Order> QueryOrder(Query<OrderCondition> queryInfo)
{
OrderService service = new OrderService();
return service.Query(queryInfo);
}
}
}
最后我们拿 SoapUI 来測试一下：
再来看看错误处理，假设有益输错 UserName：
顺便要赞一下 SoapUI，真是 WebService 调试的利器，还能够生成 .NET / Java 代码，推荐大家使用。我们用 SoapUI 生成一下 Java 代码。
Java client我决定用 CXF 来实现。所以要先配置一下 SoapUI：
JAVA CXF Client 代码：
public static void main(String[] args) {
try {
Service1 service1 = new Service1();
Service1Soap service1Soap = service1.getService1Soap();
BindingProvider provider = (BindingProvider)service1Soap;
List<Header> headers = new ArrayList<Header>();
Authentication authentication = new Authentication();
authentication.setUserName("fangxing");
authentication.setPassword("123456");
Header authHeader = new Header(ObjectFactory._Authentication_QNAME, authentication,
new JAXBDataBinding(Authentication.class));
headers.add(authHeader);
provider.getRequestContext().put(Header.HEADER_LIST, headers);
QueryOfOrderCondition queryInfo = new QueryOfOrderCondition();
queryInfo.setPageNo(1);
queryInfo.setPageSize(1000);
OrderCondition condition = new OrderCondition();
condition.setShopId("SHOP001");
condition.setStartTime("2014-05-01 00:00:00");
condition.setEndTime("2014-05-10 23:59:59");
queryInfo.setCondition(condition);
PageResultOfOrder result = service1Soap.queryOrder(queryInfo);
System.out.println("get order size: " + result.getData().getOrder().size());
} catch (Exception e) {
e.printStackTrace();
}
}
演示样例代码下载，下载请阅 Readme.txt
本文章为转载内容，我们尊重原作者对文章享有的著作权。如有内容错误或侵权问题，欢迎原作者联系我们进行内容更正或删除文章。
