【添加】软件包迁移指南

Signed-off-by: chenyong <1521761801@qq.com>

README.md

@@ -86,7 +86,7 @@ RT-Thread online packages
 ## 4、注意事项
 
  - WebClient 软件包连接 HTTPS 服务器时需要开启 WebClient 中对 TLS 功能的支持。
- - WebClient 软件包版本更新（`V1.0.0 -> 当前最新版 V2.0.0`）后软件包中函数接口和使用流程都有所变化，若开发者代码中使用之前接口，可以适配最新版本接口，或者在版本号配置中选择 `V1.0.0` 版本。
+ - WebClient 软件包版本更新（`V1.0.0 -> 当前最新版 V2.0.0`）后软件包中函数接口和使用流程都有所变化，若开发者代码中使用之前接口，可以适配最新版本接口，或者在版本号配置中选择 `V1.0.0` 版本，具体改动方式可参考软件包 [迁移指南](docs/migration-guide.md)。
 
 
 ## 5、联系方式 & 感谢

docs/migration-guide.md

@@ -0,0 +1,151 @@
+# 迁移指南
+
+本节主要介绍 WebClient 软件包版本升级之后（`V1.0.0` -> 最近版本 `V2.0.0`），软件包的改动和适配最新版本的方式。
+
+## 函数改动
+
+1. 添加 `webclient_session_create()` 创建客户端结构体函数
+
+    V1.0.0 版本客户端会话结构体不需要手动创建，V2.0.0 版本改为手动创建，用户可自定义传入的头文件长度，减少资源占用。
+
+2. `webclient_open` -> `wenclient_get`
+
+    V1.0.0 发送 GET 命令的函数 `webclient_open` 改为 `wenclient_get`，两个函数区别在于 `webclient_open` 函数只能发送默认头部信息的 GET 请求， `wenclient_get` 函数既可以发送默认也可以发送自定义头部数据的 GET 请求。
+
+3. `webclient_open_position` -> `wenclient_get_position`
+
+    同上述 `webclient_open` 函数改动类似。
+
+4. 添加 `webclient_post` 发送 POST 请求函数
+
+    V1.0.0 版本若要发送 POST 请求需要用户完成创建会话、连接、发送头部数据等整个流程，V2.0.0 版本封装了 `webclient_post` 函数完成整个 POST 请求发送流程，具体使用方式可参考 [API 手册](api.md) 和 [用户指南](user-guide.md)。
+
+5. 添加头部信息处理方式
+
+    V1.0.0 版本中没有对头部数据处理的方式，用户只能通过字符串拼接的方式来添加头部数据。V2.0.0 版本就这一问题提出相应改进方式，增加了在请求头中添加字段数据的函数（`webclient_header_fields_add`），以及通过字段名获取字段数据的函数（`webclient_header_fields_get`），方便用户添加请求头数据和获取响应头数据中信息。
+
+6. 其他功能函数添加
+
+- 添加获取当前响应状态码函数（`webclient_resp_status_get` ）；
+- 添加获取当前响应 Content-Length 数据函数（`webclient_content_length_get`）。
+
+## 流程改动
+
+### GET 请求流程改动
+
+下面以发送自定义头部数据的 GET 请求方式为例，介绍新版本软件包中 GET 流程改动。
+
+V1.0.0 版本 GET 请求流如下：
+
+- 拼接头部数据（字符串拼接方式）
+- 创建客户端会话结构体
+- 客户端与服务器建立连接
+- 发送 GET 请求头部数据
+- 接收并解析服务器下发头部数据
+- 接收服务器发送主体数据
+- 关闭连接
+
+```c
+/* 字符串处理方式拼接头部数据 */
+const char header = "xxx";
+struct webclient_session *session = RT_NULL;
+
+session = web_malloc(sizeof(struct webclient_session))
+
+webclient_connect(session, URI);
+
+webclient_send_header(session, WEBCLIENT_GET, header, strlen(header));
+
+webclient_handle_response(session);
+
+while(1)
+{
+    webclient_read(session, post_data ,strlen(post_data));
+    ...
+}
+
+webclient_close(session);
+```
+
+V2.0.0 版本 GET 请求流如下：
+
+- 创建会话结构体 
+- 拼接头部数据（函数拼接方式）
+- 发送 GET 请求头部并接收响应
+- 接收服务器下发数据
+- 关闭连接
+
+```c
+struct webclient_session *session = RT_NULL;
+
+session = webclient_session_create(1024)
+
+webclient_header_fields_add(session, "HOST: %s", URI);
+
+webclient_get(session, URI);
+
+while(1)
+{
+    webclient_read(session, buffer ,buf_sz);
+    ...
+}
+
+webclient_close(session);
+```
+
+### POST 请求流程改动
+
+下面以发送自定义头部数据的 POST 请求方式为例，介绍新版本软件包中的 POST 流程改动。
+
+V1.0.0 版本 POST 请求流如下：
+
+- 拼接头部数据（字符串拼接方式）
+- 创建客户端会话结构体
+- 客户端与服务器建立连接
+- 发送 POST 请求头部数据
+- 接收并解析服务器下发头部数据
+- 上传数据到服务器
+- 关闭连接
+
+```c
+/* 字符串处理方式拼接头部数据 */
+const char header = "xxx";
+struct webclient_session *session = RT_NULL;
+
+session = web_malloc(sizeof(struct webclient_session))
+
+webclient_connect(session, URI);
+
+webclient_send_header(session, WEBCLIENT_POST, header, strlen(header));
+
+webclient_handle_response(session);
+
+while(1)
+{
+    webclient_write(session, post_data ,strlen(post_data));
+    ...
+}
+
+webclient_close(session);
+```
+
+V2.0.0 版本 GET 请求流如下：
+
+- 创建会话结构体
+- 拼接头部数据（函数拼接方式）
+- 发送头部数据和主体数据到服务器，并接收服务器响应
+- 关闭连接
+
+```c
+struct webclient_session *session = RT_NULL;
+
+session = webclient_session_create(1024)
+
+webclient_header_fields_add(session, "Content-Length: %s", post_data_sz);
+
+webclient_post(session, URI, post_data);
+
+webclient_close(session);
+```
+
+上述介绍 WebClient 常用 GET/POST 请求方法改动，更多流程介绍请查看软件包 [使用指南](user_guide.md)。