企业官网建设流程全解析

简介：面向使用 VC++ 开发桌面程序、需要与远程服务交互的开发者，这份资料聚焦通过 COM 组件与 SOAP 协议调用 Web Service，重点解决在 C++ 工程中构造请求、发送消息并读取响应的问题，适合需要把短信接口或业务接口接入旧版项目的读者参考。压缩包内含 1 个 doc 文档，大小约 28KB，以可对照的代码示例和接口调用说明为主，内容紧凑，便于快速定位关键实现。资料已有 179 人学习，示例从创建连接器、设置服务地址与操作名、建立连接开始，再通过序列化器初始化输入流，依次构建 SOAP 信封、消息体和参数元素，把编号、电话号码、短信内容等字段写入请求，最后结束消息并读取返回结果。整体呈现从连接建立、消息序列化到响应解析的完整链路，对理解消息结构、参数嵌套及接口调用顺序也有帮助，可作为 VC++ 接入远程服务的入门参考与排错线索。

1. VC 调用 WebService：一条短信发出的完整调用长什么样

接手一个还在维护的 MFC 工单系统时，界面上有个「发送短信」按钮，点下去窗口会僵住三秒，然后弹一个「发送失败」，日志里只有一行空白。抓包才看清：程序发出去的 SOAP 报文里，命名空间写成了带?wsdl的服务地址，SoapAction末尾还多了两个空格，服务端直接回 500。问题代码就是那个类里的CWebservice_vcDlg::BeginSoap，它用 SOAP Toolkit 3.0 的SoapConnector30、SoapSerializer30、SoapReader30三个 COM 组件手工拼 XML，绕开 WSDL 解析，直接把一条短信请求发出去。这类 programming 层面的对接在今天看是老古董，但仍有大量 MFC、VC6 到 VS2010 时代的老工程要靠它对接只提供 SOAP 接口的短信网关、工单网关。你要是正在维护这种工程，或者需要在一个没有第三方库的 Win32 程序里发一次 HTTP+XML 请求，这套链路值得完整拆一遍。

2. 选型与依赖：为什么不用 SoapClient30，而走 Connector 低层链路

2.1 高层 API 与低层 API 的分水岭

SOAP Toolkit 3.0 装完之后，注册进系统的 COM 组件其实提供了两套截然不同的用法。一套是高层 API，核心是SoapClient30：先用 WSDL 生成器把服务端的?wsdl拉下来解析成一个本地 wsdl 文件，再用SoapClient30->MSSoapInit(...)加载，之后像调普通 COM 方法一样client->send(cmpcode, phone, content, date)，序列化和反序列化全由组件代劳。

另一套是低层 API，也就是原文用的这套：HttpConnector30负责传输、SoapSerializer30负责往输入流里写 XML、SoapReader30负责把输出流解析成 DOM。三件套各管一段，报文的每一个字节都由你自己决定。

老工程里选低层往往是被逼的。我遇到过的情况是：服务端是早期 Axis 生成的 WSDL，SoapClient30->MSSoapInit直接抛WSDLReader: Loading of the WSDL file failed，或者勉强加载成功但方法名被拼成了带端口类型前缀的怪名字，调用时报「找不到方法」。还有一些网关干脆不开放 WSDL，只给一份接口文档说明报文格式。这两种情况下高层 API 全部失效，只剩低层链路可走——它只依赖 HTTP POST 和一段格式正确的 XML 文本，服务端换实现、换框架、换 IP，改几个字符串就行。

代价也很明确：命名空间、元素名、元素顺序、编码声明全部要自己写对，任何一处偏差服务端都不会给你友好提示，通常就是一个 500 加一段英文 faultstring。后面第 5 章的坑基本都是这么来的。

2.2 一个 MFC 工程要备齐的依赖

真正动手前，先把环境摸清楚。这套东西不是纯头文件库，它依赖注册到系统里的 COM 组件，缺一环就是编译过或者运行时报「没有注册类」。

#import这一行是整个工程的地基，我一般把它单独放在stdafx.h的最下面，只出现一次：

// stdafx.h —— #import 只放一处，避免多个 cpp 重复生成 tlh/tli #import "mssoap30.dll" \ exclude("IStream", "ISequentialStream", "_LARGE_INTEGER", "_ULARGE_INTEGER", \ "tagSTATSTG", "_FILETIME") \ named_guids, no_namespace

exclude(...)这一串不是抄来的装饰。mssoap30.dll的类型库里自带一份IStream、_LARGE_INTEGER的定义，和 Windows SDK、和<comdef.h>里的版本撞车，不排掉就是满屏C2011: 'IStream' : struct type redefinition。named_guids让__uuidof(HttpConnector30)这类写法能成立，no_namespace则是把类型从MSSOAPLib30命名空间里放出来——不加这个，你就得把每一处ISoapConnectorPtr写成MSSOAPLib30::ISoapConnectorPtr，代码会变得很长。

提示：#import生成的头文件在中间目录里，改完exclude列表最好清理一次解决方案再重编，否则旧的.tlh会一直生效。

2.3 工程骨架与文件落位

原文只有一个对话框类的成员函数，实际能跑起来的工程至少要这几块：

CWebservice/ ├── stdafx.h # #import mssoap30.dll，全局只此一处 ├── CWebserviceApp.cpp # InitInstance 里调 AfxOleInit() ├── CWebservice_vcDlg.cpp # 界面，按钮响应里调封装类 ├── CWebservice_vcDlg.h └── Soap/ ├── SoapSmsClient.h # 封装后的调用类 └── SoapSmsClient.cpp # 连接、序列化、读响应全在这里

AfxOleInit()必须在InitInstance里调用，它等价于OleInitialize，把主线程初始化成 STA 并准备好 COM 消息泵。少了这一句，SoapConnector.CreateInstance会返回E_FAIL或者直接抛_com_error，报「尚未调用 CoInitialize」。MFC 工程里这一步经常被忽略，因为很多老项目的对话框压根没用过 COM。

3. 核心链路拆解：一次 send 调用从 Connect 到 RpcResult 的七步

3.1 连接与动作头：EndPointURL、SoapAction、Connect

原函数一开始创建连接器、设地址、设动作、连上去，四行看着简单，参数含义错一个就全盘皆输。我把常量提出来，写成一个独立的发送函数：

// 服务端点：真正的 POST 目标，不带 ?wsdl static const wchar_t* kEndpoint = L"http://sms-gw.example.com:8080/cif/services/SMS"; // 命名空间：WSDL 里的 targetNamespace，通常以 / 结尾 static const wchar_t* kNamespace = L"http://sms-gw.example.com:8080/cif/services/SMS/"; CString CSoapSmsClient::DoPost(const SmsRequest& req) { ISoapConnectorPtr spConn; ISoapSerializerPtr spSer; ISoapReaderPtr spReader; // 1) 创建 HTTP 传输连接器 HRESULT hr = spConn.CreateInstance(__uuidof(HttpConnector30)); if (FAILED(hr)) throw _com_error(hr); // 2) 端点地址：只写到服务路径，绝不带 ?wsdl spConn->Property[_bstr_t(L"EndPointURL")] = _variant_t(kEndpoint); // 3) 超时，单位毫秒；不设的话默认值在弱网下会让人怀疑人生 spConn->Property[_bstr_t(L"Timeout")] = _variant_t(8000L); // 4) SoapAction = 命名空间 + 方法名，中间不能有任何空格 CString strAction; strAction.Format(_T("%s%s"), kNamespace, _T("send")); spConn->Property[_bstr_t(L"SoapAction")] = _variant_t((LPCTSTR)strAction); // 5) 建立连接，这一步就会把 HTTP 头按需拼好 hr = spConn->Connect(); if (FAILED(hr)) throw _com_error(hr); ... }

EndPointURL是 HTTP POST 真正打过去的地址，末尾带?wsdl的话，服务端会当成「取 WSDL 文档」的 GET 请求处理，或者直接 404。SoapAction是 SOAP 1.1 独有的 HTTP 头，值必须是命名空间 + 方法名的原样拼接，服务端靠它路由到具体方法，任何多余空格都会让字符串比对失败。Timeout的参数单位是毫秒，我一般给 8 秒，网关侧处理慢的话给到 15 秒，别用默认值，默认值在生产环境里等于「不确定卡多久」。

Connect()返回的HRESULT一定要判，失败时把hr原样抛出去，后面统一在catch里翻译成人话。

3.2 消息体构造：StartEnvelope 到 EndBody 的逐行写法

这一步是整段代码里最容易写错的地方，因为序列化器不会校验你的 XML 语义，它只管按你的指令拼字符串。你让它拼错，它就乖乖拼一个错报文发出去。

// 6) 序列化器挂到连接器的输入流上 spSer.CreateInstance(__uuidof(SoapSerializer30)); spSer->Init(_variant_t((IUnknown*)spConn->InputStream)); // 7) 信封：依次是 SOAP 命名空间、字符编码、信封附加属性 spSer->StartEnvelope(L"SOAP-ENV", L"UTF-8", L""); // 8) Body 开始 spSer->StartBody(); // 9) 方法元素：名字、命名空间、前缀、元素属性 spSer->StartElement(L"send", kNamespace, L"", L""); // 10) 四个入参，依次是参数名、命名空间、前缀、属性 spSer->StartElement(L"cmpcode", kNamespace, L"", L""); spSer->WriteString(_bstr_t(_T("0166"))); // 企业代码，网关侧校验用 spSer->EndElement(); spSer->StartElement(L"phone", kNamespace, L"", L""); spSer->WriteString(_bstr_t(_T("13200000000"))); // 手机号，11 位 spSer->EndElement(); spSer->StartElement(L"content", kNamespace, L"", L""); spSer->WriteString(_bstr_t(_T("你好"))); // 短信正文 spSer->EndElement(); spSer->StartElement(L"receivedate", kNamespace, L"", L""); spSer->WriteString(_bstr_t(_T(""))); // 空串表示立即发送 spSer->EndElement(); spSer->EndElement(); // 结束 send spSer->EndBody(); spSer->EndEnvelope();

StartEnvelope的三个参数分别是信封的命名空间前缀（固定用SOAP-ENV）、字符编码声明、信封节点上的附加属性。原文把UTF-8塞在第三个位置，等于在信封上写了个UTF-8="..."的属性、而编码声明是空字符串，中文正文就很容易被服务端按 ISO-8859-1 解读成乱码。不同版本的 Toolkit 生成的.tlh里签名略有差异，#import之后在 VS 里对着StartEnvelope按一下 F12 跳进mssoap30.tlh看参数顺序，比翻任何文档都快。

StartElement的四个参数是「元素名、元素所属命名空间、前缀、元素属性字符串」。前缀传空串表示沿用默认命名空间，元素会生成成<cmpcode xmlns="..."><![CDATA[0166]]></cmpcode>这种形式。传一个NONE这类非空前缀，序列化器会老老实实生成<NONE:cmpcode>，而如果你没有对应的命名空间声明，服务端解析器直接判报文非法。参数顺序也别想当然，send的那层元素和四个子元素必须使用同一个命名空间字符串，逐字节一致，包括末尾斜杠。

3.3 发送与读响应：EndMessage、Reader->Load、RpcResult

报文写完只是躺在输入流里，真正发出去靠EndMessage。

// 11) 把消息真正 POST 出去，这一步才产生网络 IO hr = spConn->EndMessage(); if (FAILED(hr)) throw _com_error(hr); // 12) 读取器接连接器的输出流 spReader.CreateInstance(__uuidof(SoapReader30)); spReader->Load(_variant_t((IUnknown*)spConn->OutputStream), L""); // 13) 取返回值：rpc/encoded 风格的服务端在 RpcResult 里 CString strRet; _variant_t vText = spReader->RpcResult->text; if (vText.vt == VT_BSTR && vText.bstrVal != NULL) { strRet = (LPCTSTR)_bstr_t(vText.bstrVal); } return strRet;

EndMessage是整个流程里唯一产生网络往返的调用，卡住三秒就是它。Load的第二个参数是附加在读取流上的 HTTP 头，正常传空串即可，传一个空格会被拼进默认头里。RpcResult只在服务端返回 rpc/encoded 风格报文时才有值，return 节点没写、或者服务端走的是 document/literal，RpcResult拿到的就是空节点，->text取值会失败。稳妥的兜底是拿原始 XML：

// 兜底：直接取 Body 的 XML 文本，自己按节点名找结果 if (strRet.IsEmpty() && spReader->Body != NULL) { strRet = (LPCTSTR)_bstr_t(spReader->Body->xml); }

拿到这段 XML 之后，用IXMLDOMNodePtr或者干脆CString::Find定位<return>标签都行，老服务端的报文结构通常很稳定，字符串截取比再引一层解析更省事。

3.4 异常兜底：_com_error 里该取哪几个字段

原文的catch (_com_error e)有两个毛病：按值捕获会多拷贝一份对象，而且只返回了Description()，把最有价值的Error()和Source()丢掉了。调网关的时候，Description()经常是空的，真正有用的是 HRESULT 数值，服务端 500 和本地网络超时的错误码完全不同。

catch (_com_error& e) // 按引用捕获 { CString strMsg; strMsg.Format(_T("[SOAP] hr=0x%08X src=%s desc=%s msg=%s"), (unsigned)e.Error(), (LPCTSTR)(_bstr_t)e.Source(), (LPCTSTR)(_bstr_t)e.Description(), (LPCTSTR)(_bstr_t)e.ErrorMessage()); // 落日志文件，不要只弹 MessageBox ::OutputDebugString(strMsg); return strMsg; }

Error()是 HRESULT，Source()一般返回触发异常的组件名（比如HttpConnector30），ErrorMessage()是系统消息表里的标准描述。四个字段一起打到日志里，下次再出问题就不用抓包猜了。抓包工具在手边的时候也别忘了留一份完整请求报文，第 6 章会讲怎么在代码里把Envelope->xml打出来对照。

4. 工程化封装：把 BeginSoap 从对话框里抽成一个可复用类

4.1 原函数的三处硬伤

原文的CString CWebservice_vcDlg::BeginSoap(CString UserName, CString Password, CString WebUrl)收了三个参数，函数体里一个都没用，端点、命名空间、方法名全是写死的字符串，连企业代码和手机号都硬编码在报文里。这属于典型的先跑通再说的写法，放测试机没问题，一旦要接第二个网关、要改一条短信模板，就得满工程找字符串。

第二处硬伤是端点地址和命名空间混用。原文把?wsdl既写进了EndPointURL，又写进了每个StartElement的命名空间参数，还把带端口的完整地址当作命名空间。这三者在 WSDL 里是三个不同的东西：soap:address location是端点、targetNamespace是命名空间、soapAction是动作。混着用的结果是报文看起来像那么回事，服务端一解析就报错。

第三处是返回值设计。失败时统一返回一个空格字符串" "，调用方根本判断不了到底是网络不通、参数不对还是服务端内部错误。

4.2 用结构体承载请求和结果

我把请求和结果都做成结构体，调用方只关心填参数和看结果：

// SoapSmsClient.h #pragma once struct SmsRequest { CString strCmpCode; // 企业代码，网关开户时分配 CString strPhone; // 手机号，不带国家码 CString strContent; // 短信正文，UTF-8 编码后按网关限制截断 CString strReceiveDate; // 定时发送时间，空串表示立即发送 }; struct SmsResult { bool bOk = false; // 是否成功 int nHr = 0; // HRESULT，失败时用于排查 CString strPayload; // 成功时服务端返回的原文 CString strError; // 失败时的可读描述 }; class CSoapSmsClient { public: void SetEndpoint(LPCTSTR lpszUrl, LPCTSTR lpszNs, LPCTSTR lpszAction); void SetTimeout(int nMs) { m_nTimeoutMs = nMs; } SmsResult Send(const SmsRequest& req); private: CString DoPost(const SmsRequest& req); CString m_strEndpoint = _T("http://sms-gw.example.com:8080/cif/services/SMS"); CString m_strNamespace = _T("http://sms-gw.example.com:8080/cif/services/SMS/"); CString m_strAction = _T("send"); int m_nTimeoutMs = 8000; };

Send里面不再直接抛异常，而是统一转成SmsResult返回，把_com_error关在实现文件内部：

SmsResult CSoapSmsClient::Send(const SmsRequest& req) { SmsResult res; try { res.strPayload = DoPost(req); // 内部完成建连、序列化、发送、读响应 res.bOk = !res.strPayload.IsEmpty(); if (!res.bOk) res.strError = _T("服务端返回空报文"); } catch (_com_error& e) { res.bOk = false; res.nHr = (int)e.Error(); res.strError.Format(_T("SOAP 调用失败 hr=0x%08X desc=%s"), (unsigned)e.Error(), (LPCTSTR)(_bstr_t)e.Description()); } return res; }

DoPost就是第 3 章那段代码，只是把常量换成了成员变量，SetEndpoint用来在配置加载后覆盖默认值。nHr单独留一个字段，好处是上层可以根据错误码做差异化处理，比如0x800C0005这类传输层错误直接重试一次，业务层错误就不重试。

4.3 COM 初始化与线程归属

封装类本身不负责 COM 初始化，这件事必须在调用线程上做，而且只有两个正确位置。

主线程走 MFC 的AfxOleInit()：

BOOL CCWebserviceApp::InitInstance() { if (!AfxOleInit()) { // 等价于 OleInitialize，STA AfxMessageBox(_T("COM 初始化失败")); return FALSE; } ... }

如果发送动作被放进了工作线程（界面不卡的关键），线程入口必须自己来一遍：

UINT CWorkerThread(LPVOID pParam) { // HttpConnector30 是 apartment 线程模型，工作线程必须自己初始化 HRESULT hr = ::CoInitializeEx(NULL, COINIT_APARTMENTTHREADED); if (FAILED(hr)) return 0; CSoapSmsClient client; // 只能在本线程创建和使用 SmsResult r = client.Send(*(SmsRequest*)pParam); ::CoUninitialize(); // 与上面的 CoInitializeEx 成对出现 return 0; }

这里有个反面教材：为了省事把主线程创建好的ISoapConnectorPtr直接塞给工作线程用，结果是0x8001010E（RPC_E_WRONG_THREAD），或者偶发成功、偶发崩溃，属于典型的玄学 bug。COM 接口指针跨 apartment 传递必须 marshal，与其折腾CoMarshalInterThreadInterfaceInStream，不如在每个线程里各建一套，成本极低，逻辑极清晰。

注意：CoInitializeEx和CoUninitialize必须配对，return提前退出也要确保CoUninitialize走到，用 RAII 包一层更稳。

5. 常见问题排查：五个让调用静默失败的坑

5.1 编译期：#import 的 IStream 冲突与命名空间缺失

现象：加完#import "mssoap30.dll"之后，工程里冒出几十条C2011重定义错误，全部指向IStream、_LARGE_INTEGER、tagSTATSTG；或者另一台机器上不报重定义，改成报「ISoapConnectorPtr未定义」。

原因：mssoap30.dll的类型库里自带一份基础类型定义，和<comdef.h>、Windows SDK 里的版本重复；而「未定义」那条是no_namespace没加，所有类型都被塞进了MSSOAPLib30命名空间。

解决：把第 2 章那行#import原样抄过去，exclude列表一个参数都别删，再带上named_guids, no_namespace。改完之后清理中间目录重编，因为mssoap30.tlh是增量生成的，不清理会读到旧文件。

5.2 连接期：EndPointURL 带 ?wsdl 与超时缺省

现象：调用不报错，但EndMessage之后RpcResult为空；或者接口偶发卡住十几秒然后失败，服务端日志里连请求都没记录。

原因：EndPointURL末尾带了?wsdl，HTTP 层把它当成查询参数发出去，服务端按「取 WSDL」的路由处理，返回的是一段 XML 文档而不是方法调用结果。超时没设则是另一回事，HttpConnector30的默认值在弱网下会拖很久，表现为界面长时间无响应。

解决：EndPointURL只写到服务路径，?wsdl只在用浏览器查看接口定义时用；同时显式设Property["Timeout"]，单位毫秒，我给 8000 到 15000 之间。两个属性都在Connect()之前设置，Connect之后再改不生效。

5.3 调用期：SoapAction 与命名空间错位导致 500

现象：服务端稳定返回 HTTP 500，响应体里是Server did not recognize the value of HTTP Header SOAPAction，或者Unexpected element send。

原因：SoapAction是由命名空间和方法名直接拼出来的，命名空间字符串末尾多一个空格、少一个斜杠，都会导致拼出来的动作和服务端注册的不一致。原文里命名空间常量末尾带两个空格，拼上send就成了...SMS/ send，肉眼几乎看不出来，服务端字符串比对必然失败。另一类原因是StartElement里给send元素传的命名空间和SoapAction用的不是同一个字符串。

解决：命名空间和动作都提成全局常量，拼SoapAction时用Format(_T("%s%s"))而不是手写+，避免_bstr_t隐式转换时带进额外字符。定位阶段把spSer生成的报文用spConn->InputStream打出来对照 WSDL 里的targetNamespace，一眼就能看出多没多空格。

5.4 数据期：中文乱码与 RpcResult 取值失败

现象：短信发出去是问号或者方块；或者代码在strRet = CString((const char*)spReader->RpcResult->text)这一行编译不过/运行时崩溃。

原因：前者是信封编码声明没写对，StartEnvelope的第二个参数才是字符编码，写在第三个位置等于没声明，服务端按默认单字节编码解析中文；后者是IXMLDOMNode::text返回的是VARIANT而不是字符串，直接用(const char*)强转属于类型错配，Unicode 工程下更会读出乱码。

解决：StartEnvelope(L"SOAP-ENV", L"UTF-8", L"")，编码就放第二个参数；取返回值统一走_variant_t中转再转CString，先判断vt == VT_BSTR再取值。正文超过 70 个汉字时按网关限制截断，截断时别把 UTF-8 的多字节序列切断，按CString字符数截而不是字节数截。

5.5 部署期：x64 工程加载不了 32 位 COM

现象：开发机上跑得好好的，换一台机器或者换成 Release x64 编译之后，程序启动就报「没有注册类」，错误码0x80040154。

原因：mssoap30.dll是 32 位组件，注册表里只写了Wow6432Node下的 CLSID，64 位进程去 64 位视图里找，当然找不到；另一种情况是新机器根本没装 SOAP Toolkit，只拷了 exe 过去。

解决：解决方案配置管理器里把平台锁死为 Win32，别让默认的 x64 混进来；部署时要么在目标机注册mssoap30.dll，要么在程序目录放一份组件并用免注册 COM 的 manifest 声明依赖。交付前我一定会在一台干净机器上跑一遍安装包，这一步省不得。

6. 二次开发：把硬编码端点改成配置驱动并加三道验证关卡

真正要长期维护这套代码，第一件事是把写死的字符串赶到配置文件里去。我用最土的办法，GetPrivateProfileString读一个和 exe 同目录的 ini，改配置不用重编译，现场调试时运维自己就能改：

void CSoapSmsClient::LoadConfig(LPCTSTR lpszIni) { TCHAR szBuf[512] = {0}; ::GetPrivateProfileString(_T("sms"), _T("EndPoint"), _T(""), szBuf, 512, lpszIni); if (_tcslen(szBuf) > 0) m_strEndpoint = szBuf; // 空值则沿用默认 ::GetPrivateProfileString(_T("sms"), _T("Namespace"), _T(""), szBuf, 512, lpszIni); if (_tcslen(szBuf) > 0) m_strNamespace = szBuf; m_nTimeoutMs = ::GetPrivateProfileInt(_T("sms"), _T("TimeoutMs"), 8000, lpszIni); }

GetPrivateProfileString的第四个参数是缓冲区长度，给 512 够用了，端点地址不会比这长。读不到配置项时返回默认值，别让它变成空串——空 EndPointURL 会让Connect抛一个非常难懂的错误。

改造完成之后加三道验证关卡，缺一道就会在某个环节翻车。第一道是报文自检：在EndMessage之前把spSer写入的内容从InputStream读出来打日志，人工核对命名空间、元素顺序、编码声明；第二道是对照测试：同一份报文贴进接口测试工具里发一次，工具能过而程序不过，问题一定在 HTTP 头（多半是SoapAction）而不是报文本身；第三道是异常注入：把端点指向一个不存在的地址、把超时改成 1 毫秒，确认SmsResult里的nHr和strError都有内容而不是空字符串。

早年间我图省事跳过第二道，结果在一个客户现场耗了整整一个下午，最后发现是命名空间常量末尾粘了一个制表符，肉眼完全看不出来。从那以后我每次改这类报文参数，都强制把生成的 XML 和 WSDL 里的targetNamespace并排放进日志里跑一遍对比，多花三十秒，省掉的是整下午的抓包。希望这些能帮到你，少走一遍这条老路。

本文还有配套的精品资源，点击获取