🎨 规范mp模块的javadoc接口注释文档

2025-11-24 08:33:19 +08:00 · 2025-10-28 11:54:06 +08:00
parent b26c786797
commit de4848b2f7
13 changed files with 1361 additions and 733 deletions
--- a/weixin-java-mp/src/main/java/me/chanjar/weixin/mp/api/WxMpAiOpenService.java
+++ b/weixin-java-mp/src/main/java/me/chanjar/weixin/mp/api/WxMpAiOpenService.java
@@ -6,74 +6,112 @@ import me.chanjar.weixin.common.error.WxErrorException;
 import me.chanjar.weixin.mp.enums.AiLangType;

 /**
- * <pre>
- * 微信AI开放接口（语音识别，微信翻译）.
- * https://mp.weixin.qq.com/wiki?t=resource/res_main&id=21516712282KzWVE
- *  Created by BinaryWang on 2018/6/9.
- * </pre>
+ * 微信AI开放接口（语音识别，微信翻译）
+ * <p>
+ * 提供微信AI相关的功能，包括语音识别、微信翻译等。
+ * 支持上传语音文件进行语音识别，以及文本翻译功能。
+ * </p>
+ * <p>
+ * 详情请见：<a href="https://mp.weixin.qq.com/wiki?t=resource/res_main&id=21516712282KzWVE">微信AI开放接口</a>
+ * </p>
+ * Created by BinaryWang on 2018/6/9.
 *
 * @author <a href="https://github.com/binarywang">Binary Wang</a>
 */
 public interface WxMpAiOpenService {

-  /**
-   * <pre>
-   * 提交语音.
-   * http请求方式: POST
-   * http://api.weixin.qq.com/cgi-bin/media/voice/addvoicetorecofortext?access_token=ACCESS_TOKEN&format=&voice_id=xxxxxx&lang=zh_CN
-   * </pre>
-   *
-   * @param voiceId   语音唯一标识
-   * @param lang      语言，zh_CN 或 en_US，默认中文
-   * @param voiceFile 语音文件
-   * @throws WxErrorException the wx error exception
-   */
-  void uploadVoice(String voiceId, AiLangType lang, File voiceFile) throws WxErrorException;
+    /**
+     * <pre>
+     * 提交语音
+     * </pre>
+     *
+     * @param voiceId   语音唯一标识
+     * @param lang      语言，zh_CN 或 en_US，默认中文
+     * @param voiceFile 语音文件
+     * @throws WxErrorException 微信API调用异常，可能包括：
+     *                          <ul>
+     *                            <li>40001 - 获取access_token时AppSecret错误，或者access_token无效</li>
+     *                            <li>40002 - 请确保grant_type字段值为client_credential</li>
+     *                            <li>40003 - appid对应公众号请开发者使用绑定的公众号测试</li>
+     *                            <li>40004 - appid不正确</li>
+     *                            <li>40006 - access_token超时</li>
+     *                            <li>48001 - api功能未授权</li>
+     *                            <li>45009 - 调用接口的QPS超限</li>
+     *                            <li>其他业务错误码</li>
+     *                          </ul>
+     * @see <a href="http://api.weixin.qq.com/cgi-bin/media/voice/addvoicetorecofortext">提交语音接口</a>
+     */
+    void uploadVoice(String voiceId, AiLangType lang, File voiceFile) throws WxErrorException;

-  /**
-   * <pre>
-   * 获取语音识别结果.
-   * 接口调用请求说明
-   *
-   * http://api.weixin.qq.com/cgi-bin/media/voice/queryrecoresultfortext?access_token=ACCESS_TOKEN&voice_id=xxxxxx&lang=zh_CN
-   * 请注意，添加完文件之后10s内调用这个接口
-   *
-   * </pre>
-   *
-   * @param voiceId 语音唯一标识
-   * @param lang    语言，zh_CN 或 en_US，默认中文
-   * @return the string
-   * @throws WxErrorException the wx error exception
-   */
-  String queryRecognitionResult(String voiceId, AiLangType lang) throws WxErrorException;
+    /**
+     * <pre>
+     * 获取语音识别结果
+     * 请注意，添加完文件之后10s内调用这个接口
+     * </pre>
+     *
+     * @param voiceId 语音唯一标识
+     * @param lang    语言，zh_CN 或 en_US，默认中文
+     * @return 语音识别结果文本
+     * @throws WxErrorException 微信API调用异常，可能包括：
+     *                          <ul>
+     *                            <li>40001 - 获取access_token时AppSecret错误，或者access_token无效</li>
+     *                            <li>40002 - 请确保grant_type字段值为client_credential</li>
+     *                            <li>40003 - appid对应公众号请开发者使用绑定的公众号测试</li>
+     *                            <li>40004 - appid不正确</li>
+     *                            <li>40006 - access_token超时</li>
+     *                            <li>48001 - api功能未授权</li>
+     *                            <li>45009 - 调用接口的QPS超限</li>
+     *                            <li>其他业务错误码</li>
+     *                          </ul>
+     * @see <a href="http://api.weixin.qq.com/cgi-bin/media/voice/queryrecoresultfortext">获取语音识别结果接口</a>
+     */
+    String queryRecognitionResult(String voiceId, AiLangType lang) throws WxErrorException;

-  /**
-   * 识别指定语音文件内容.
-   * 此方法揉合了前两两个方法：uploadVoice 和 queryRecognitionResult
-   *
-   * @param voiceId   语音唯一标识
-   * @param lang      语言，zh_CN 或 en_US，默认中文
-   * @param voiceFile 语音文件
-   * @return the string
-   * @throws WxErrorException the wx error exception
-   */
-  String recogniseVoice(String voiceId, AiLangType lang, File voiceFile) throws WxErrorException;
+    /**
+     * <pre>
+     * 识别指定语音文件内容
+     * 此方法揉合了前两两个方法：uploadVoice 和 queryRecognitionResult
+     * </pre>
+     *
+     * @param voiceId   语音唯一标识
+     * @param lang      语言，zh_CN 或 en_US，默认中文
+     * @param voiceFile 语音文件
+     * @return 语音识别结果文本
+     * @throws WxErrorException 微信API调用异常，可能包括：
+     *                          <ul>
+     *                            <li>40001 - 获取access_token时AppSecret错误，或者access_token无效</li>
+     *                            <li>40002 - 请确保grant_type字段值为client_credential</li>
+     *                            <li>40003 - appid对应公众号请开发者使用绑定的公众号测试</li>
+     *                            <li>40004 - appid不正确</li>
+     *                            <li>40006 - access_token超时</li>
+     *                            <li>48001 - api功能未授权</li>
+     *                            <li>45009 - 调用接口的QPS超限</li>
+     *                            <li>其他业务错误码</li>
+     *                          </ul>
+     */
+    String recogniseVoice(String voiceId, AiLangType lang, File voiceFile) throws WxErrorException;

-  /**
-   * <pre>
-   * 微信翻译.
-   * 接口调用请求说明
-   *
-   * http请求方式: POST
-   * http://api.weixin.qq.com/cgi-bin/media/voice/translatecontent?access_token=ACCESS_TOKEN&lfrom=xxx&lto=xxx
-   *
-   * </pre>
-   *
-   * @param langFrom 源语言，zh_CN 或 en_US
-   * @param langTo   目标语言，zh_CN 或 en_US
-   * @param content  要翻译的文本内容
-   * @return the string
-   * @throws WxErrorException the wx error exception
-   */
-  String translate(AiLangType langFrom, AiLangType langTo, String content) throws WxErrorException;
+    /**
+     * <pre>
+     * 微信翻译
+     * </pre>
+     *
+     * @param langFrom 源语言，zh_CN 或 en_US
+     * @param langTo   目标语言，zh_CN 或 en_US
+     * @param content  要翻译的文本内容
+     * @return 翻译结果文本
+     * @throws WxErrorException 微信API调用异常，可能包括：
+     *                          <ul>
+     *                            <li>40001 - 获取access_token时AppSecret错误，或者access_token无效</li>
+     *                            <li>40002 - 请确保grant_type字段值为client_credential</li>
+     *                            <li>40003 - appid对应公众号请开发者使用绑定的公众号测试</li>
+     *                            <li>40004 - appid不正确</li>
+     *                            <li>40006 - access_token超时</li>
+     *                            <li>48001 - api功能未授权</li>
+     *                            <li>45009 - 调用接口的QPS超限</li>
+     *                            <li>其他业务错误码</li>
+     *                          </ul>
+     * @see <a href="http://api.weixin.qq.com/cgi-bin/media/voice/translatecontent">微信翻译接口</a>
+     */
+    String translate(AiLangType langFrom, AiLangType langTo, String content) throws WxErrorException;
 }
--- a/weixin-java-mp/src/main/java/me/chanjar/weixin/mp/api/WxMpCardService.java
+++ b/weixin-java-mp/src/main/java/me/chanjar/weixin/mp/api/WxMpCardService.java
@@ -7,298 +7,611 @@ import me.chanjar.weixin.mp.bean.card.*;
 import java.util.List;

 /**
- * 卡券相关接口.
+ * 卡券相关接口
+ * <p>
+ * 提供微信卡券的创建、查询、核销、管理等功能。
+ * 支持卡券API签名生成、卡券Code解码、卡券核销、库存管理等功能。
+ * </p>
+ * <p>
+ * 详情请见：<a href="https://mp.weixin.qq.com/wiki/7/aaa137b55fb2e0456bf8dd9148dd613f.html">卡券开发文档</a>
+ * </p>
 *
 * @author YuJian(mgcnrx11 @ hotmail.com) on 01/11/2016
 * @author yuanqixun 2018-08-29
 */
 public interface WxMpCardService {
    /**
-     * 得到WxMpService.
+     * <pre>
+     * 获取WxMpService实例
+     * </pre>
     *
-     * @return WxMpService wx mp service
+     * @return WxMpService实例
     */
    WxMpService getWxMpService();

    /**
-     * 获得卡券api_ticket，不强制刷新卡券api_ticket.
+     * <pre>
+     * 获得卡券api_ticket，不强制刷新卡券api_ticket
+     * </pre>
     *
-     * @return 卡券api_ticket card api ticket
-     * @throws WxErrorException 异常
-     * @see #getCardApiTicket(boolean) #getCardApiTicket(boolean)#getCardApiTicket(boolean)
+     * @return 卡券api_ticket
+     * @throws WxErrorException 微信API调用异常，可能包括：
+     *                          <ul>
+     *                            <li>40001 - 获取access_token时AppSecret错误，或者access_token无效</li>
+     *                            <li>40002 - 请确保grant_type字段值为client_credential</li>
+     *                            <li>40003 - appid对应公众号请开发者使用绑定的公众号测试</li>
+     *                            <li>40004 - appid不正确</li>
+     *                            <li>40006 - access_token超时</li>
+     *                            <li>48001 - api功能未授权</li>
+     *                            <li>45009 - 调用接口的QPS超限</li>
+     *                            <li>其他业务错误码</li>
+     *                          </ul>
+     * @see #getCardApiTicket(boolean)
     */
    String getCardApiTicket() throws WxErrorException;

    /**
     * <pre>
-     * 获得卡券api_ticket.
+     * 获得卡券api_ticket
     * 获得时会检查卡券apiToken是否过期，如果过期了，那么就刷新一下，否则就什么都不干
-     *
-     * 详情请见：http://mp.weixin.qq.com/wiki/7/aaa137b55fb2e0456bf8dd9148dd613f.html#.E9.99.84.E5.BD.954-.E5.8D.A1.E5.88.B8.E6.89.A9.E5.B1.95.E5.AD.97.E6.AE.B5.E5.8F.8A.E7.AD.BE.E5.90.8D.E7.94.9F.E6.88.90.E7.AE.97.E6.B3.95
     * </pre>
     *
-     * @param forceRefresh 强制刷新
-     * @return 卡券api_ticket card api ticket
-     * @throws WxErrorException 异常
+     * @param forceRefresh 强制刷新，如果为true则强制刷新api_ticket
+     * @return 卡券api_ticket
+     * @throws WxErrorException 微信API调用异常，可能包括：
+     *                          <ul>
+     *                            <li>40001 - 获取access_token时AppSecret错误，或者access_token无效</li>
+     *                            <li>40002 - 请确保grant_type字段值为client_credential</li>
+     *                            <li>40003 - appid对应公众号请开发者使用绑定的公众号测试</li>
+     *                            <li>40004 - appid不正确</li>
+     *                            <li>40006 - access_token超时</li>
+     *                            <li>48001 - api功能未授权</li>
+     *                            <li>45009 - 调用接口的QPS超限</li>
+     *                            <li>其他业务错误码</li>
+     *                          </ul>
+     * @see <a href="https://mp.weixin.qq.com/wiki/7/aaa137b55fb2e0456bf8dd9148dd613f.html#.E9.99.84.E5.BD.954-.E5.8D.A1.E5.88.B8.E6.89.A9.E5.B1.95.E5.AD.97.E6.AE.B5.E5.8F.8A.E7.AD.BE.E5.90.8D.E7.94.9F.E6.88.90.E7.AE.97.E6.B3.95">卡券签名生成算法</a>
     */
    String getCardApiTicket(boolean forceRefresh) throws WxErrorException;

    /**
     * <pre>
-     * 创建调用卡券api时所需要的签名.
-     *
-     * 详情请见：http://mp.weixin.qq.com/wiki/7/aaa137b55fb2e0456bf8dd9148dd613f.html#.E9.99.84.E5.BD
-     * .954-.E5.8D.A1.E5.88.B8.E6.89.A9.E5.B1.95.E5.AD.97.E6.AE.B5.E5.8F.8A.E7.AD.BE.E5.90.8D.E7.94
-     * .9F.E6.88.90.E7.AE.97.E6.B3.95
+     * 创建调用卡券api时所需要的签名
     * </pre>
     *
-     * @param optionalSignParam 参与签名的参数数组。可以为下列字段：app_id, card_id, card_type, code, openid, location_id                          </br>注意：当做wx.chooseCard调用时，必须传入app_id参与签名，否则会造成签名失败导致拉取卡券列表为空
-     * @return 卡券Api签名对象 wx card api signature
-     * @throws WxErrorException 异常
+     * @param optionalSignParam 参与签名的参数数组。可以为下列字段：app_id, card_id, card_type, code, openid, location_id
+     *                          注意：当做wx.chooseCard调用时，必须传入app_id参与签名，否则会造成签名失败导致拉取卡券列表为空
+     * @return 卡券Api签名对象
+     * @throws WxErrorException 微信API调用异常，可能包括：
+     *                          <ul>
+     *                            <li>40001 - 获取access_token时AppSecret错误，或者access_token无效</li>
+     *                            <li>40002 - 请确保grant_type字段值为client_credential</li>
+     *                            <li>40003 - appid对应公众号请开发者使用绑定的公众号测试</li>
+     *                            <li>40004 - appid不正确</li>
+     *                            <li>40006 - access_token超时</li>
+     *                            <li>48001 - api功能未授权</li>
+     *                            <li>45009 - 调用接口的QPS超限</li>
+     *                            <li>其他业务错误码</li>
+     *                          </ul>
+     * @see <a href="https://mp.weixin.qq.com/wiki/7/aaa137b55fb2e0456bf8dd9148dd613f.html#.E9.99.84.E5.BD.954-.E5.8D.A1.E5.88.B8.E6.89.A9.E5.B1.95.E5.AD.97.E6.AE.B5.E5.8F.8A.E7.AD.BE.E5.90.8D.E7.94.9F.E6.88.90.E7.AE.97.E6.B3.95">卡券签名生成算法</a>
     */
    WxCardApiSignature createCardApiSignature(String... optionalSignParam) throws WxErrorException;

    /**
-     * 卡券Code解码.
+     * <pre>
+     * 卡券Code解码
+     * </pre>
     *
     * @param encryptCode 加密Code，通过JSSDK的chooseCard接口获得
-     * @return 解密后的Code string
-     * @throws WxErrorException 异常
+     * @return 解密后的Code
+     * @throws WxErrorException 微信API调用异常，可能包括：
+     *                          <ul>
+     *                            <li>40001 - 获取access_token时AppSecret错误，或者access_token无效</li>
+     *                            <li>40002 - 请确保grant_type字段值为client_credential</li>
+     *                            <li>40003 - appid对应公众号请开发者使用绑定的公众号测试</li>
+     *                            <li>40004 - appid不正确</li>
+     *                            <li>40006 - access_token超时</li>
+     *                            <li>48001 - api功能未授权</li>
+     *                            <li>45009 - 调用接口的QPS超限</li>
+     *                            <li>其他业务错误码</li>
+     *                          </ul>
     */
    String decryptCardCode(String encryptCode) throws WxErrorException;

    /**
-     * 卡券Code查询.
-     * 文档地址： https://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1451025272&anchor=1
+     * <pre>
+     * 卡券Code查询
+     * </pre>
     *
     * @param cardId       卡券ID代表一类卡券
     * @param code         单张卡券的唯一标准
     * @param checkConsume 是否校验code核销状态，填入true和false时的code异常状态返回数据不同
-     * @return WxMpCardResult对象 wx mp card result
-     * @throws WxErrorException 异常
+     * @return WxMpCardResult对象，包含卡券查询结果信息
+     * @throws WxErrorException 微信API调用异常，可能包括：
+     *                          <ul>
+     *                            <li>40001 - 获取access_token时AppSecret错误，或者access_token无效</li>
+     *                            <li>40002 - 请确保grant_type字段值为client_credential</li>
+     *                            <li>40003 - appid对应公众号请开发者使用绑定的公众号测试</li>
+     *                            <li>40004 - appid不正确</li>
+     *                            <li>40006 - access_token超时</li>
+     *                            <li>48001 - api功能未授权</li>
+     *                            <li>45009 - 调用接口的QPS超限</li>
+     *                            <li>其他业务错误码</li>
+     *                          </ul>
+     * @see <a href="https://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1451025272&anchor=1">卡券Code查询接口</a>
     */
    WxMpCardResult queryCardCode(String cardId, String code, boolean checkConsume) throws WxErrorException;

    /**
+     * <pre>
     * 卡券Code核销。核销失败会抛出异常
+     * </pre>
     *
     * @param code 单张卡券的唯一标准
-     * @return 调用返回的JSON字符串 。可用 com.google.gson.JsonParser#parse 等方法直接取JSON串中的errcode等信息。
-     * @throws WxErrorException 异常
+     * @return 调用返回的JSON字符串，可用 com.google.gson.JsonParser#parse 等方法直接取JSON串中的errcode等信息
+     * @throws WxErrorException 微信API调用异常，可能包括：
+     *                          <ul>
+     *                            <li>40001 - 获取access_token时AppSecret错误，或者access_token无效</li>
+     *                            <li>40002 - 请确保grant_type字段值为client_credential</li>
+     *                            <li>40003 - appid对应公众号请开发者使用绑定的公众号测试</li>
+     *                            <li>40004 - appid不正确</li>
+     *                            <li>40006 - access_token超时</li>
+     *                            <li>48001 - api功能未授权</li>
+     *                            <li>45009 - 调用接口的QPS超限</li>
+     *                            <li>其他业务错误码</li>
+     *                          </ul>
     */
    String consumeCardCode(String code) throws WxErrorException;

    /**
-     * 卡券Code核销。核销失败会抛出异常.
+     * <pre>
+     * 卡券Code核销。核销失败会抛出异常
+     * </pre>
     *
     * @param code   单张卡券的唯一标准
     * @param cardId 当自定义Code卡券时需要传入card_id
-     * @return 调用返回的JSON字符串 。可用 com.google.gson.JsonParser#parse 等方法直接取JSON串中的errcode等信息。
-     * @throws WxErrorException 异常
+     * @return 调用返回的JSON字符串，可用 com.google.gson.JsonParser#parse 等方法直接取JSON串中的errcode等信息
+     * @throws WxErrorException 微信API调用异常，可能包括：
+     *                          <ul>
+     *                            <li>40001 - 获取access_token时AppSecret错误，或者access_token无效</li>
+     *                            <li>40002 - 请确保grant_type字段值为client_credential</li>
+     *                            <li>40003 - appid对应公众号请开发者使用绑定的公众号测试</li>
+     *                            <li>40004 - appid不正确</li>
+     *                            <li>40006 - access_token超时</li>
+     *                            <li>48001 - api功能未授权</li>
+     *                            <li>45009 - 调用接口的QPS超限</li>
+     *                            <li>其他业务错误码</li>
+     *                          </ul>
     */
    String consumeCardCode(String code, String cardId) throws WxErrorException;

    /**
-     * 卡券Mark接口.
+     * <pre>
+     * 卡券Mark接口
     * 开发者在帮助消费者核销卡券之前，必须帮助先将此code（卡券串码）与一个openid绑定（即mark住），
     * 才能进一步调用核销接口，否则报错。
+     * </pre>
     *
     * @param code   卡券的code码
     * @param cardId 卡券的ID
     * @param openId 用券用户的openid
     * @param isMark 是否要mark（占用）这个code，填写true或者false，表示占用或解除占用
-     * @throws WxErrorException 异常
+     * @throws WxErrorException 微信API调用异常，可能包括：
+     *                          <ul>
+     *                            <li>40001 - 获取access_token时AppSecret错误，或者access_token无效</li>
+     *                            <li>40002 - 请确保grant_type字段值为client_credential</li>
+     *                            <li>40003 - appid对应公众号请开发者使用绑定的公众号测试</li>
+     *                            <li>40004 - appid不正确</li>
+     *                            <li>40006 - access_token超时</li>
+     *                            <li>48001 - api功能未授权</li>
+     *                            <li>45009 - 调用接口的QPS超限</li>
+     *                            <li>其他业务错误码</li>
+     *                          </ul>
     */
    void markCardCode(String code, String cardId, String openId, boolean isMark) throws WxErrorException;

    /**
-     * 查看卡券详情接口.
-     * 详见 https://mp.weixin.qq.com/wiki/14/8dd77aeaee85f922db5f8aa6386d385e.html#.E6.9F.A5.E7.9C.8B.E5.8D.A1.E5.88.B8.E8.AF.A6.E6.83.85
+     * <pre>
+     * 查看卡券详情接口
+     * </pre>
     *
     * @param cardId 卡券的ID
-     * @return 返回的卡券详情JSON字符串 <br> [注] 由于返回的JSON格式过于复杂，难以定义其对应格式的Bean并且难以维护，因此只返回String格式的JSON串。 <br> 可由 com.google.gson.JsonParser#parse 等方法直接取JSON串中的某个字段。
-     * @throws WxErrorException 异常
+     * @return 返回的卡券详情JSON字符串
+     *          [注] 由于返回的JSON格式过于复杂，难以定义其对应格式的Bean并且难以维护，因此只返回String格式的JSON串。
+     *          可由 com.google.gson.JsonParser#parse 等方法直接取JSON串中的某个字段。
+     * @throws WxErrorException 微信API调用异常，可能包括：
+     *                          <ul>
+     *                            <li>40001 - 获取access_token时AppSecret错误，或者access_token无效</li>
+     *                            <li>40002 - 请确保grant_type字段值为client_credential</li>
+     *                            <li>40003 - appid对应公众号请开发者使用绑定的公众号测试</li>
+     *                            <li>40004 - appid不正确</li>
+     *                            <li>40006 - access_token超时</li>
+     *                            <li>48001 - api功能未授权</li>
+     *                            <li>45009 - 调用接口的QPS超限</li>
+     *                            <li>其他业务错误码</li>
+     *                          </ul>
+     * @see <a href="https://mp.weixin.qq.com/wiki/14/8dd77aeaee85f922db5f8aa6386d385e.html#.E6.9F.A5.E7.9C.8B.E5.8D.A1.E5.88.B8.E8.AF.A6.E6.83.85">查看卡券详情</a>
     */
    String getCardDetail(String cardId) throws WxErrorException;

    /**
-     * 添加测试白名单.
+     * <pre>
+     * 添加测试白名单
+     * </pre>
     *
     * @param openid 用户的openid
-     * @return string string
-     * @throws WxErrorException 异常
+     * @return 操作结果字符串
+     * @throws WxErrorException 微信API调用异常，可能包括：
+     *                          <ul>
+     *                            <li>40001 - 获取access_token时AppSecret错误，或者access_token无效</li>
+     *                            <li>40002 - 请确保grant_type字段值为client_credential</li>
+     *                            <li>40003 - appid对应公众号请开发者使用绑定的公众号测试</li>
+     *                            <li>40004 - appid不正确</li>
+     *                            <li>40006 - access_token超时</li>
+     *                            <li>48001 - api功能未授权</li>
+     *                            <li>45009 - 调用接口的QPS超限</li>
+     *                            <li>其他业务错误码</li>
+     *                          </ul>
     */
    String addTestWhiteList(String openid) throws WxErrorException;

    /**
-     * 创建卡券.
+     * <pre>
+     * 创建卡券
+     * </pre>
     *
-     * @param cardCreateMessage 请求
-     * @return result wx mp card create result
-     * @throws WxErrorException 异常
+     * @param cardCreateRequest 卡券创建请求对象
+     * @return 卡券创建结果对象
+     * @throws WxErrorException 微信API调用异常，可能包括：
+     *                          <ul>
+     *                            <li>40001 - 获取access_token时AppSecret错误，或者access_token无效</li>
+     *                            <li>40002 - 请确保grant_type字段值为client_credential</li>
+     *                            <li>40003 - appid对应公众号请开发者使用绑定的公众号测试</li>
+     *                            <li>40004 - appid不正确</li>
+     *                            <li>40006 - access_token超时</li>
+     *                            <li>48001 - api功能未授权</li>
+     *                            <li>45009 - 调用接口的QPS超限</li>
+     *                            <li>其他业务错误码</li>
+     *                          </ul>
     */
    WxMpCardCreateResult createCard(WxMpCardCreateRequest cardCreateMessage) throws WxErrorException;

    /**
-     * 创建卡券二维码.
+     * <pre>
+     * 创建卡券二维码
+     * </pre>
     *
     * @param cardId   卡券编号
     * @param outerStr 二维码标识
-     * @return WxMpCardQrcodeCreateResult wx mp card qrcode create result
-     * @throws WxErrorException 异常
+     * @return 卡券二维码创建结果对象
+     * @throws WxErrorException 微信API调用异常，可能包括：
+     *                          <ul>
+     *                            <li>40001 - 获取access_token时AppSecret错误，或者access_token无效</li>
+     *                            <li>40002 - 请确保grant_type字段值为client_credential</li>
+     *                            <li>40003 - appid对应公众号请开发者使用绑定的公众号测试</li>
+     *                            <li>40004 - appid不正确</li>
+     *                            <li>40006 - access_token超时</li>
+     *                            <li>48001 - api功能未授权</li>
+     *                            <li>45009 - 调用接口的QPS超限</li>
+     *                            <li>其他业务错误码</li>
+     *                          </ul>
     */
    WxMpCardQrcodeCreateResult createQrcodeCard(String cardId, String outerStr) throws WxErrorException;

    /**
-     * 创建卡券二维码.
+     * <pre>
+     * 创建卡券二维码
+     * </pre>
     *
     * @param cardId    卡券编号
-     * @param outerStr  二维码标识
+     * @param outerStr  用户首次领卡时，会通过 领取事件推送 给商户； 对于会员卡的二维码，用户每次扫码打开会员卡后点击任何url，会将该值拼入url中，方便开发者定位扫码来源
     * @param expiresIn 指定二维码的有效时间，范围是60 ~ 1800秒。不填默认为365天有效
-     * @return WxMpCardQrcodeCreateResult wx mp card qrcode create result
-     * @throws WxErrorException 异常
+     * @return 卡券二维码创建结果对象
+     * @throws WxErrorException 微信API调用异常，可能包括：
+     *                          <ul>
+     *                            <li>40001 - 获取access_token时AppSecret错误，或者access_token无效</li>
+     *                            <li>40002 - 请确保grant_type字段值为client_credential</li>
+     *                            <li>40003 - appid对应公众号请开发者使用绑定的公众号测试</li>
+     *                            <li>40004 - appid不正确</li>
+     *                            <li>40006 - access_token超时</li>
+     *                            <li>48001 - api功能未授权</li>
+     *                            <li>45009 - 调用接口的QPS超限</li>
+     *                            <li>其他业务错误码</li>
+     *                          </ul>
     */
    WxMpCardQrcodeCreateResult createQrcodeCard(String cardId, String outerStr, int expiresIn) throws WxErrorException;

    /**
-     * 创建卡券二维码.
+     * <pre>
+     * 创建卡券二维码
+     * </pre>
     *
     * @param cardId       卡券编号
     * @param outerStr     用户首次领卡时，会通过 领取事件推送 给商户； 对于会员卡的二维码，用户每次扫码打开会员卡后点击任何url，会将该值拼入url中，方便开发者定位扫码来源
     * @param expiresIn    指定二维码的有效时间，范围是60 ~ 1800秒。不填默认为365天有效
-     * @param openid       指定领取者的openid，只有该用户能领取。bind_openid字段为true的卡券必须填写，非指定openid不必填写。
-     * @param code         卡券Code码,use_custom_code字段为true的卡券必须填写，非自定义code和导入code模式的卡券不必填写。
-     * @param isUniqueCode 指定下发二维码，生成的二维码随机分配一个code，领取后不可再次扫描。填写true或false。默认false，注意填写该字段时，卡券须通过审核且库存不为0。
-     * @return WxMpCardQrcodeCreateResult wx mp card qrcode create result
-     * @throws WxErrorException 异常
+     * @param openid       指定领取者的openid，只有该用户能领取。bind_openid字段为true的卡券必须填写，非指定openid不必填写
+     * @param code         卡券Code码,use_custom_code字段为true的卡券必须填写，非自定义code和导入code模式的卡券不必填写
+     * @param isUniqueCode 指定下发二维码，生成的二维码随机分配一个code，领取后不可再次扫描。填写true或false。默认false，注意填写该字段时，卡券须通过审核且库存不为0
+     * @return 卡券二维码创建结果对象
+     * @throws WxErrorException 微信API调用异常，可能包括：
+     *                          <ul>
+     *                            <li>40001 - 获取access_token时AppSecret错误，或者access_token无效</li>
+     *                            <li>40002 - 请确保grant_type字段值为client_credential</li>
+     *                            <li>40003 - appid对应公众号请开发者使用绑定的公众号测试</li>
+     *                            <li>40004 - appid不正确</li>
+     *                            <li>40006 - access_token超时</li>
+     *                            <li>48001 - api功能未授权</li>
+     *                            <li>45009 - 调用接口的QPS超限</li>
+     *                            <li>其他业务错误码</li>
+     *                          </ul>
     */
    WxMpCardQrcodeCreateResult createQrcodeCard(String cardId, String outerStr, int expiresIn, String openid,
                                              String code, boolean isUniqueCode) throws WxErrorException;

    /**
-     * 创建卡券货架.
+     * <pre>
+     * 创建卡券货架
+     * </pre>
     *
     * @param createRequest 货架创建参数
-     * @return WxMpCardLandingPageCreateResult wx mp card landing page create result
-     * @throws WxErrorException 异常
+     * @return 货架创建结果对象
+     * @throws WxErrorException 微信API调用异常，可能包括：
+     *                          <ul>
+     *                            <li>40001 - 获取access_token时AppSecret错误，或者access_token无效</li>
+     *                            <li>40002 - 请确保grant_type字段值为client_credential</li>
+     *                            <li>40003 - appid对应公众号请开发者使用绑定的公众号测试</li>
+     *                            <li>40004 - appid不正确</li>
+     *                            <li>40006 - access_token超时</li>
+     *                            <li>48001 - api功能未授权</li>
+     *                            <li>45009 - 调用接口的QPS超限</li>
+     *                            <li>其他业务错误码</li>
+     *                          </ul>
     */
    WxMpCardLandingPageCreateResult createLandingPage(WxMpCardLandingPageCreateRequest createRequest)
    throws WxErrorException;

    /**
-     * 将用户的卡券设置为失效状态.
-     * 详见:https://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1451025272&anchor=9
+     * <pre>
+     * 将用户的卡券设置为失效状态
+     * </pre>
     *
     * @param cardId 卡券编号
     * @param code   用户会员卡号
     * @param reason 设置为失效的原因
-     * @return result string
-     * @throws WxErrorException 异常
+     * @return 操作结果字符串
+     * @throws WxErrorException 微信API调用异常，可能包括：
+     *                          <ul>
+     *                            <li>40001 - 获取access_token时AppSecret错误，或者access_token无效</li>
+     *                            <li>40002 - 请确保grant_type字段值为client_credential</li>
+     *                            <li>40003 - appid对应公众号请开发者使用绑定的公众号测试</li>
+     *                            <li>40004 - appid不正确</li>
+     *                            <li>40006 - access_token超时</li>
+     *                            <li>48001 - api功能未授权</li>
+     *                            <li>45009 - 调用接口的QPS超限</li>
+     *                            <li>其他业务错误码</li>
+     *                          </ul>
+     * @see <a href="https://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1451025272&anchor=9">设置卡券失效</a>
     */
    String unavailableCardCode(String cardId, String code, String reason) throws WxErrorException;

    /**
-     * 删除卡券接口.
+     * <pre>
+     * 删除卡券接口
+     * </pre>
     *
     * @param cardId 卡券id
-     * @return 删除结果 wx mp card delete result
-     * @throws WxErrorException 异常
+     * @return 删除结果对象
+     * @throws WxErrorException 微信API调用异常，可能包括：
+     *                          <ul>
+     *                            <li>40001 - 获取access_token时AppSecret错误，或者access_token无效</li>
+     *                            <li>40002 - 请确保grant_type字段值为client_credential</li>
+     *                            <li>40003 - appid对应公众号请开发者使用绑定的公众号测试</li>
+     *                            <li>40004 - appid不正确</li>
+     *                            <li>40006 - access_token超时</li>
+     *                            <li>48001 - api功能未授权</li>
+     *                            <li>45009 - 调用接口的QPS超限</li>
+     *                            <li>其他业务错误码</li>
+     *                          </ul>
     */
    WxMpCardDeleteResult deleteCard(String cardId) throws WxErrorException;

    /**
+     * <pre>
     * 导入自定义code(仅对自定义code商户)
+     * </pre>
     *
     * @param cardId   卡券id
-     * @param codeList 需导入微信卡券后台的自定义code，上限为100个。
-     * @return the wx mp card code deposit result
-     * @throws WxErrorException the wx error exception
+     * @param codeList 需导入微信卡券后台的自定义code，上限为100个
+     * @return 导入结果对象
+     * @throws WxErrorException 微信API调用异常，可能包括：
+     *                          <ul>
+     *                            <li>40001 - 获取access_token时AppSecret错误，或者access_token无效</li>
+     *                            <li>40002 - 请确保grant_type字段值为client_credential</li>
+     *                            <li>40003 - appid对应公众号请开发者使用绑定的公众号测试</li>
+     *                            <li>40004 - appid不正确</li>
+     *                            <li>40006 - access_token超时</li>
+     *                            <li>48001 - api功能未授权</li>
+     *                            <li>45009 - 调用接口的QPS超限</li>
+     *                            <li>其他业务错误码</li>
+     *                          </ul>
     */
    WxMpCardCodeDepositResult cardCodeDeposit(String cardId, List<String> codeList) throws WxErrorException;

    /**
+     * <pre>
     * 查询导入code数目接口
+     * </pre>
     *
     * @param cardId 卡券id
-     * @return the wx mp card code deposit count result
-     * @throws WxErrorException the wx error exception
+     * @return 查询结果对象
+     * @throws WxErrorException 微信API调用异常，可能包括：
+     *                          <ul>
+     *                            <li>40001 - 获取access_token时AppSecret错误，或者access_token无效</li>
+     *                            <li>40002 - 请确保grant_type字段值为client_credential</li>
+     *                            <li>40003 - appid对应公众号请开发者使用绑定的公众号测试</li>
+     *                            <li>40004 - appid不正确</li>
+     *                            <li>40006 - access_token超时</li>
+     *                            <li>48001 - api功能未授权</li>
+     *                            <li>45009 - 调用接口的QPS超限</li>
+     *                            <li>其他业务错误码</li>
+     *                          </ul>
     */
    WxMpCardCodeDepositCountResult cardCodeDepositCount(String cardId) throws WxErrorException;

    /**
+     * <pre>
     * 核查code接口
+     * </pre>
     *
     * @param cardId   卡券id
     * @param codeList 已经微信卡券后台的自定义code，上限为100个
-     * @return the wx mp card code checkcode result
-     * @throws WxErrorException the wx error exception
+     * @return 核查结果对象
+     * @throws WxErrorException 微信API调用异常，可能包括：
+     *                          <ul>
+     *                            <li>40001 - 获取access_token时AppSecret错误，或者access_token无效</li>
+     *                            <li>40002 - 请确保grant_type字段值为client_credential</li>
+     *                            <li>40003 - appid对应公众号请开发者使用绑定的公众号测试</li>
+     *                            <li>40004 - appid不正确</li>
+     *                            <li>40006 - access_token超时</li>
+     *                            <li>48001 - api功能未授权</li>
+     *                            <li>45009 - 调用接口的QPS超限</li>
+     *                            <li>其他业务错误码</li>
+     *                          </ul>
     */
    WxMpCardCodeCheckcodeResult cardCodeCheckcode(String cardId, List<String> codeList) throws WxErrorException;

    /**
+     * <pre>
     * 图文消息群发卡券获取内嵌html
+     * </pre>
     *
     * @param cardId 卡券id
-     * @return the wx mp card mpnews gethtml result
-     * @throws WxErrorException the wx error exception
+     * @return HTML获取结果对象
+     * @throws WxErrorException 微信API调用异常，可能包括：
+     *                          <ul>
+     *                            <li>40001 - 获取access_token时AppSecret错误，或者access_token无效</li>
+     *                            <li>40002 - 请确保grant_type字段值为client_credential</li>
+     *                            <li>40003 - appid对应公众号请开发者使用绑定的公众号测试</li>
+     *                            <li>40004 - appid不正确</li>
+     *                            <li>40006 - access_token超时</li>
+     *                            <li>48001 - api功能未授权</li>
+     *                            <li>45009 - 调用接口的QPS超限</li>
+     *                            <li>其他业务错误码</li>
+     *                          </ul>
     */
    WxMpCardMpnewsGethtmlResult cardMpnewsGethtml(String cardId) throws WxErrorException;

-
    /**
+     * <pre>
     * 修改库存接口
-     * https://developers.weixin.qq.com/doc/offiaccount/Cards_and_Offer/Managing_Coupons_Vouchers_and_Cards.html#5
+     * </pre>
     *
     * @param cardId      卡券ID
     * @param changeValue 库存变更值，负值为减少库存
-     * @throws WxErrorException the wx error exception
+     * @throws WxErrorException 微信API调用异常，可能包括：
+     *                          <ul>
+     *                            <li>40001 - 获取access_token时AppSecret错误，或者access_token无效</li>
+     *                            <li>40002 - 请确保grant_type字段值为client_credential</li>
+     *                            <li>40003 - appid对应公众号请开发者使用绑定的公众号测试</li>
+     *                            <li>40004 - appid不正确</li>
+     *                            <li>40006 - access_token超时</li>
+     *                            <li>48001 - api功能未授权</li>
+     *                            <li>45009 - 调用接口的QPS超限</li>
+     *                            <li>其他业务错误码</li>
+     *                          </ul>
+     * @see <a href="https://developers.weixin.qq.com/doc/offiaccount/Cards_and_Offer/Managing_Coupons_Vouchers_and_Cards.html#5">修改库存接口</a>
     */
    void cardModifyStock(String cardId, Integer changeValue) throws WxErrorException;

-
    /**
+     * <pre>
     * 更改Code接口
-     * https://developers.weixin.qq.com/doc/offiaccount/Cards_and_Offer/Managing_Coupons_Vouchers_and_Cards.html#6
+     * </pre>
     *
     * @param cardId  卡券ID
     * @param oldCode 需变更的Code码
     * @param newCode 变更后的有效Code码
-     * @throws WxErrorException the wx error exception
+     * @throws WxErrorException 微信API调用异常，可能包括：
+     *                          <ul>
+     *                            <li>40001 - 获取access_token时AppSecret错误，或者access_token无效</li>
+     *                            <li>40002 - 请确保grant_type字段值为client_credential</li>
+     *                            <li>40003 - appid对应公众号请开发者使用绑定的公众号测试</li>
+     *                            <li>40004 - appid不正确</li>
+     *                            <li>40006 - access_token超时</li>
+     *                            <li>48001 - api功能未授权</li>
+     *                            <li>45009 - 调用接口的QPS超限</li>
+     *                            <li>其他业务错误码</li>
+     *                          </ul>
+     * @see <a href="https://developers.weixin.qq.com/doc/offiaccount/Cards_and_Offer/Managing_Coupons_Vouchers_and_Cards.html#6">更改Code接口</a>
     */
    void cardCodeUpdate(String cardId, String oldCode, String newCode) throws WxErrorException;

    /**
+     * <pre>
     * 设置买单接口
-     * https://developers.weixin.qq.com/doc/offiaccount/Cards_and_Offer/Create_a_Coupon_Voucher_or_Card.html#12
+     * </pre>
     *
     * @param cardId 卡券ID
     * @param isOpen 是否开启买单功能，填true/false
-     * @throws WxErrorException the wx error exception
+     * @throws WxErrorException 微信API调用异常，可能包括：
+     *                          <ul>
+     *                            <li>40001 - 获取access_token时AppSecret错误，或者access_token无效</li>
+     *                            <li>40002 - 请确保grant_type字段值为client_credential</li>
+     *                            <li>40003 - appid对应公众号请开发者使用绑定的公众号测试</li>
+     *                            <li>40004 - appid不正确</li>
+     *                            <li>40006 - access_token超时</li>
+     *                            <li>48001 - api功能未授权</li>
+     *                            <li>45009 - 调用接口的QPS超限</li>
+     *                            <li>其他业务错误码</li>
+     *                          </ul>
+     * @see <a href="https://developers.weixin.qq.com/doc/offiaccount/Cards_and_Offer/Create_a_Coupon_Voucher_or_Card.html#12">设置买单接口</a>
     */
    void cardPaycellSet(String cardId, Boolean isOpen) throws WxErrorException;

    /**
+     * <pre>
     * 设置自助核销
-     * https://developers.weixin.qq.com/doc/offiaccount/Cards_and_Offer/Create_a_Coupon_Voucher_or_Card.html#14
+     * </pre>
     *
     * @param cardId           卡券ID
     * @param isOpen           是否开启自助核销功能
     * @param needVerifyCod    用户核销时是否需要输入验证码， 填true/false， 默认为false
     * @param needRemarkAmount 用户核销时是否需要备注核销金额， 填true/false， 默认为false
-     * @throws WxErrorException the wx error exception
+     * @throws WxErrorException 微信API调用异常，可能包括：
+     *                          <ul>
+     *                            <li>40001 - 获取access_token时AppSecret错误，或者access_token无效</li>
+     *                            <li>40002 - 请确保grant_type字段值为client_credential</li>
+     *                            <li>40003 - appid对应公众号请开发者使用绑定的公众号测试</li>
+     *                            <li>40004 - appid不正确</li>
+     *                            <li>40006 - access_token超时</li>
+     *                            <li>48001 - api功能未授权</li>
+     *                            <li>45009 - 调用接口的QPS超限</li>
+     *                            <li>其他业务错误码</li>
+     *                          </ul>
+     * @see <a href="https://developers.weixin.qq.com/doc/offiaccount/Cards_and_Offer/Create_a_Coupon_Voucher_or_Card.html#14">设置自助核销</a>
     */
    void cardSelfConsumeCellSet(String cardId, Boolean isOpen,
                              Boolean needVerifyCod, Boolean needRemarkAmount) throws WxErrorException;

    /**
+     * <pre>
     * 获取用户已领取卡券接口
-     * https://developers.weixin.qq.com/doc/offiaccount/Cards_and_Offer/Managing_Coupons_Vouchers_and_Cards.html#1
+     * </pre>
     *
     * @param openId 需要查询的用户openid
     * @param cardId 卡券ID。不填写时默认查询当前appid下的卡券
-     * @return user card list
-     * @throws WxErrorException the wx error exception
+     * @return 用户卡券列表结果对象
+     * @throws WxErrorException 微信API调用异常，可能包括：
+     *                          <ul>
+     *                            <li>40001 - 获取access_token时AppSecret错误，或者access_token无效</li>
+     *                            <li>40002 - 请确保grant_type字段值为client_credential</li>
+     *                            <li>40003 - appid对应公众号请开发者使用绑定的公众号测试</li>
+     *                            <li>40004 - appid不正确</li>
+     *                            <li>40006 - access_token超时</li>
+     *                            <li>48001 - api功能未授权</li>
+     *                            <li>45009 - 调用接口的QPS超限</li>
+     *                            <li>其他业务错误码</li>
+     *                          </ul>
+     * @see <a href="https://developers.weixin.qq.com/doc/offiaccount/Cards_and_Offer/Managing_Coupons_Vouchers_and_Cards.html#1">获取用户已领取卡券接口</a>
     */
    WxUserCardListResult getUserCardList(String openId, String cardId) throws WxErrorException;
-
 }
--- a/weixin-java-mp/src/main/java/me/chanjar/weixin/mp/api/WxMpKefuService.java
+++ b/weixin-java-mp/src/main/java/me/chanjar/weixin/mp/api/WxMpKefuService.java
@@ -29,9 +29,9 @@ public interface WxMpKefuService {
     * 接口url格式：https://api.weixin.qq.com/cgi-bin/message/custom/send?access_token=ACCESS_TOKEN
     * </pre>
     *
-     * @param message the message
-     * @return the boolean
-     * @throws WxErrorException 异常
+     * @param message 客服消息对象，包含消息类型、内容、接收者等信息
+     * @return 发送是否成功，true表示成功，false表示失败
+     * @throws WxErrorException 微信API调用异常
     */
    boolean sendKefuMessage(WxMpKefuMessage message) throws WxErrorException;

@@ -42,9 +42,9 @@ public interface WxMpKefuService {
     * 接口url格式：https://api.weixin.qq.com/cgi-bin/message/custom/send?access_token=ACCESS_TOKEN
     * </pre>
     *
-     * @param message the message
-     * @return the response
-     * @throws WxErrorException 异常
+     * @param message 客服消息对象，包含消息类型、内容、接收者等信息
+     * @return 微信API响应结果，JSON格式字符串
+     * @throws WxErrorException 微信API调用异常
     */
    String sendKefuMessageWithResponse(WxMpKefuMessage message) throws WxErrorException;

@@ -57,8 +57,8 @@ public interface WxMpKefuService {
     * 接口url格式：https://api.weixin.qq.com/cgi-bin/customservice/getkflist?access_token=ACCESS_TOKEN
     * </pre>
     *
-     * @return the wx mp kf list
-     * @throws WxErrorException 异常
+     * @return 客服基本信息列表，包含客服账号、昵称、头像等信息
+     * @throws WxErrorException 微信API调用异常
     */
    WxMpKfList kfList() throws WxErrorException;

@@ -69,8 +69,8 @@ public interface WxMpKefuService {
     * 接口url格式：https://api.weixin.qq.com/cgi-bin/customservice/getonlinekflist?access_token=ACCESS_TOKEN
     * </pre>
     *
-     * @return the wx mp kf online list
-     * @throws WxErrorException 异常
+     * @return 在线客服接待信息列表，包含在线客服账号、接待状态等信息
+     * @throws WxErrorException 微信API调用异常
     */
    WxMpKfOnlineList kfOnlineList() throws WxErrorException;

@@ -81,9 +81,9 @@ public interface WxMpKefuService {
     * 接口url格式：https://api.weixin.qq.com/customservice/kfaccount/add?access_token=ACCESS_TOKEN
     * </pre>
     *
-     * @param request the request
-     * @return the boolean
-     * @throws WxErrorException 异常
+     * @param request 客服账号请求对象，包含客服账号、昵称等信息
+     * @return 添加是否成功，true表示成功，false表示失败
+     * @throws WxErrorException 微信API调用异常
     */
    boolean kfAccountAdd(WxMpKfAccountRequest request) throws WxErrorException;

@@ -94,22 +94,22 @@ public interface WxMpKefuService {
     * 接口url格式：https://api.weixin.qq.com/customservice/kfaccount/update?access_token=ACCESS_TOKEN
     * </pre>
     *
-     * @param request the request
-     * @return the boolean
-     * @throws WxErrorException the wx error exception
+     * @param request 客服账号请求对象，包含客服账号、昵称等信息
+     * @return 更新是否成功，true表示成功，false表示失败
+     * @throws WxErrorException 微信API调用异常
     */
    boolean kfAccountUpdate(WxMpKfAccountRequest request) throws WxErrorException;

    /**
     * <pre>
-     * 设置客服信息（即更新客服信息）
+     * 邀请绑定客服账号
     * 详情请见：<a href="http://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1458044813&token=&lang=zh_CN">客服管理</a>
     * 接口url格式：https://api.weixin.qq.com/customservice/kfaccount/inviteworker?access_token=ACCESS_TOKEN
     * </pre>
     *
-     * @param request the request
-     * @return the boolean
-     * @throws WxErrorException 异常
+     * @param request 客服账号请求对象，包含客服账号、邀请者微信号等信息
+     * @return 邀请是否成功，true表示成功，false表示失败
+     * @throws WxErrorException 微信API调用异常
     */
    boolean kfAccountInviteWorker(WxMpKfAccountRequest request) throws WxErrorException;

@@ -120,10 +120,10 @@ public interface WxMpKefuService {
     * 接口url格式：https://api.weixin.qq.com/customservice/kfaccount/uploadheadimg?access_token=ACCESS_TOKEN&kf_account=KFACCOUNT
     * </pre>
     *
-     * @param kfAccount the kf account
-     * @param imgFile   the img file
-     * @return the boolean
-     * @throws WxErrorException 异常
+     * @param kfAccount 客服账号，格式为：账号前缀@微信号
+     * @param imgFile   头像图片文件，支持JPG、PNG格式，大小不超过2MB
+     * @return 上传是否成功，true表示成功，false表示失败
+     * @throws WxErrorException 微信API调用异常
     */
    boolean kfAccountUploadHeadImg(String kfAccount, File imgFile) throws WxErrorException;

@@ -134,9 +134,9 @@ public interface WxMpKefuService {
     * 接口url格式：https://api.weixin.qq.com/customservice/kfaccount/del?access_token=ACCESS_TOKEN&kf_account=KFACCOUNT
     * </pre>
     *
-     * @param kfAccount the kf account
-     * @return the boolean
-     * @throws WxErrorException 异常
+     * @param kfAccount 客服账号，格式为：账号前缀@微信号
+     * @return 删除是否成功，true表示成功，false表示失败
+     * @throws WxErrorException 微信API调用异常
     */
    boolean kfAccountDel(String kfAccount) throws WxErrorException;

@@ -150,10 +150,10 @@ public interface WxMpKefuService {
     * 接口url格式： https://api.weixin.qq.com/customservice/kfsession/create?access_token=ACCESS_TOKEN
     * </pre>
     *
-     * @param openid    the openid
-     * @param kfAccount the kf account
-     * @return the boolean
-     * @throws WxErrorException 异常
+     * @param openid    用户的openid，标识具体的用户
+     * @param kfAccount 客服账号，格式为：账号前缀@微信号
+     * @return 创建是否成功，true表示成功，false表示失败
+     * @throws WxErrorException 微信API调用异常
     */
    boolean kfSessionCreate(String openid, String kfAccount) throws WxErrorException;

@@ -165,10 +165,10 @@ public interface WxMpKefuService {
     * 接口url格式： https://api.weixin.qq.com/customservice/kfsession/close?access_token=ACCESS_TOKEN
     * </pre>
     *
-     * @param openid    the openid
-     * @param kfAccount the kf account
-     * @return the boolean
-     * @throws WxErrorException 异常
+     * @param openid    用户的openid，标识具体的用户
+     * @param kfAccount 客服账号，格式为：账号前缀@微信号
+     * @return 关闭是否成功，true表示成功，false表示失败
+     * @throws WxErrorException 微信API调用异常
     */
    boolean kfSessionClose(String openid, String kfAccount) throws WxErrorException;

@@ -180,9 +180,9 @@ public interface WxMpKefuService {
     * 接口url格式： https://api.weixin.qq.com/customservice/kfsession/getsession?access_token=ACCESS_TOKEN&openid=OPENID
     * </pre>
     *
-     * @param openid the openid
-     * @return the wx mp kf session get result
-     * @throws WxErrorException 异常
+     * @param openid 用户的openid，标识具体的用户
+     * @return 客户会话状态信息，包含客服账号、会话状态等
+     * @throws WxErrorException 微信API调用异常
     */
    WxMpKfSessionGetResult kfSessionGet(String openid) throws WxErrorException;

@@ -194,9 +194,9 @@ public interface WxMpKefuService {
     * 接口url格式： https://api.weixin.qq.com/customservice/kfsession/getsessionlist?access_token=ACCESS_TOKEN&kf_account=KFACCOUNT
     * </pre>
     *
-     * @param kfAccount the kf account
-     * @return the wx mp kf session list
-     * @throws WxErrorException 异常
+     * @param kfAccount 客服账号，格式为：账号前缀@微信号
+     * @return 客服会话列表，包含正在接待的会话信息
+     * @throws WxErrorException 微信API调用异常
     */
    WxMpKfSessionList kfSessionList(String kfAccount) throws WxErrorException;

@@ -208,8 +208,8 @@ public interface WxMpKefuService {
     * 接口url格式： https://api.weixin.qq.com/customservice/kfsession/getwaitcase?access_token=ACCESS_TOKEN
     * </pre>
     *
-     * @return the wx mp kf session wait case list
-     * @throws WxErrorException 异常
+     * @return 未接入会话列表，包含等待接入的会话信息
+     * @throws WxErrorException 微信API调用异常
     */
    WxMpKfSessionWaitCaseList kfSessionGetWaitCase() throws WxErrorException;

@@ -223,12 +223,12 @@ public interface WxMpKefuService {
     * 接口url格式： https://api.weixin.qq.com/customservice/msgrecord/getmsglist?access_token=ACCESS_TOKEN
     * </pre>
     *
-     * @param startTime 起始时间
-     * @param endTime   结束时间
-     * @param msgId     消息id顺序从小到大，从1开始
-     * @param number    每次获取条数，最多10000条
-     * @return 聊天记录对象 wx mp kf msg list
-     * @throws WxErrorException 异常
+     * @param startTime 起始时间，用于筛选聊天记录的时间范围
+     * @param endTime   结束时间，用于筛选聊天记录的时间范围
+     * @param msgId     消息id顺序从小到大，从1开始，用于分页获取
+     * @param number    每次获取条数，最多10000条，用于分页控制
+     * @return 聊天记录对象，包含客服和用户的聊天消息列表
+     * @throws WxErrorException 微信API调用异常
     */
    WxMpKfMsgList kfMsgList(Date startTime, Date endTime, Long msgId, Integer number) throws WxErrorException;

@@ -240,17 +240,17 @@ public interface WxMpKefuService {
     * 接口url格式： https://api.weixin.qq.com/customservice/msgrecord/getmsglist?access_token=ACCESS_TOKEN
     * </pre>
     *
-     * @param startTime 起始时间
-     * @param endTime   结束时间
-     * @return 聊天记录对象 wx mp kf msg list
-     * @throws WxErrorException 异常
+     * @param startTime 起始时间，用于筛选聊天记录的时间范围
+     * @param endTime   结束时间，用于筛选聊天记录的时间范围
+     * @return 聊天记录对象，包含客服和用户的聊天消息列表
+     * @throws WxErrorException 微信API调用异常
     */
    WxMpKfMsgList kfMsgList(Date startTime, Date endTime) throws WxErrorException;

    /**
     * <pre>
     * 客服输入状态
-     * 开发者可通过调用“客服输入状态”接口，返回客服当前输入状态给用户。
+     * 开发者可通过调用"客服输入状态"接口，返回客服当前输入状态给用户。
     * 此接口需要客服消息接口权限。
     * 如果不满足发送客服消息的触发条件，则无法下发输入状态。
     * 下发输入状态，需要客服之前30秒内跟用户有过消息交互。
@@ -261,10 +261,10 @@ public interface WxMpKefuService {
     * 接口url格式：https://api.weixin.qq.com/cgi-bin/message/custom/typing?access_token=ACCESS_TOKEN
     * </pre>
     *
-     * @param openid  用户id
-     * @param command "Typing"：对用户下发“正在输入"状态 "CancelTyping"：取消对用户的”正在输入"状态
-     * @return the boolean
-     * @throws WxErrorException 异常
+     * @param openid  用户的openid，标识具体的用户
+     * @param command 输入状态命令，可选值："Typing"：对用户下发"正在输入"状态；"CancelTyping"：取消对用户的"正在输入"状态
+     * @return 发送是否成功，true表示成功，false表示失败
+     * @throws WxErrorException 微信API调用异常
     */
    boolean sendKfTypingState(String openid, String command) throws WxErrorException;
 }
--- a/weixin-java-mp/src/main/java/me/chanjar/weixin/mp/api/WxMpMassMessageService.java
+++ b/weixin-java-mp/src/main/java/me/chanjar/weixin/mp/api/WxMpMassMessageService.java
@@ -8,138 +8,234 @@ import me.chanjar.weixin.mp.bean.result.WxMpMassSpeedGetResult;
 import me.chanjar.weixin.mp.bean.result.WxMpMassUploadResult;

 /**
- * <pre>
- * 群发消息服务类.
+ * 群发消息服务类
+ * <p>
+ * 提供微信公众号群发消息的功能，包括图文消息、视频消息的群发，
+ * 支持按分组群发、按openid列表群发、消息预览、群发状态查询等功能。
+ * </p>
+ * <p>
+ * 详情请见：<a href="http://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1421140549">群发消息开发文档</a>
+ * </p>
 * Created by Binary Wang on 2017-8-16.
- * </pre>
 *
 * @author <a href="https://github.com/binarywang">Binary Wang</a>
 */
 public interface WxMpMassMessageService {
    /**
     * <pre>
-     * 上传群发用的图文消息，上传后才能群发图文消息.
-     *
-     * 详情请见: http://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1421140549&token=&lang=zh_CN
+     * 上传群发用的图文消息，上传后才能群发图文消息
     * </pre>
     *
-     * @param news the news
-     * @return the wx mp mass upload result
-     * @throws WxErrorException the wx error exception
-     * @see #massGroupMessageSend(WxMpMassTagMessage) #massGroupMessageSend(WxMpMassTagMessage)
-     * @see #massOpenIdsMessageSend(WxMpMassOpenIdsMessage) #massOpenIdsMessageSend(WxMpMassOpenIdsMessage)
+     * @param news 图文消息对象
+     * @return 上传结果对象，包含media_id等信息
+     * @throws WxErrorException 微信API调用异常，可能包括：
+     *                          <ul>
+     *                            <li>40001 - 获取access_token时AppSecret错误，或者access_token无效</li>
+     *                            <li>40002 - 请确保grant_type字段值为client_credential</li>
+     *                            <li>40003 - appid对应公众号请开发者使用绑定的公众号测试</li>
+     *                            <li>40004 - appid不正确</li>
+     *                            <li>40006 - access_token超时</li>
+     *                            <li>48001 - api功能未授权</li>
+     *                            <li>45009 - 调用接口的QPS超限</li>
+     *                            <li>其他业务错误码</li>
+     *                          </ul>
+     * @see #massGroupMessageSend(WxMpMassTagMessage)
+     * @see #massOpenIdsMessageSend(WxMpMassOpenIdsMessage)
+     * @see <a href="http://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1421140549">上传群发用的图文消息</a>
     */
    WxMpMassUploadResult massNewsUpload(WxMpMassNews news) throws WxErrorException;

    /**
     * <pre>
-     * 上传群发用的视频，上传后才能群发视频消息.
-     * 详情请见: http://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1421140549&token=&lang=zh_CN
+     * 上传群发用的视频，上传后才能群发视频消息
     * </pre>
     *
-     * @param video the video
-     * @return the wx mp mass upload result
-     * @throws WxErrorException the wx error exception
-     * @see #massGroupMessageSend(WxMpMassTagMessage) #massGroupMessageSend(WxMpMassTagMessage)
-     * @see #massOpenIdsMessageSend(WxMpMassOpenIdsMessage) #massOpenIdsMessageSend(WxMpMassOpenIdsMessage)
+     * @param video 视频消息对象
+     * @return 上传结果对象，包含media_id等信息
+     * @throws WxErrorException 微信API调用异常，可能包括：
+     *                          <ul>
+     *                            <li>40001 - 获取access_token时AppSecret错误，或者access_token无效</li>
+     *                            <li>40002 - 请确保grant_type字段值为client_credential</li>
+     *                            <li>40003 - appid对应公众号请开发者使用绑定的公众号测试</li>
+     *                            <li>40004 - appid不正确</li>
+     *                            <li>40006 - access_token超时</li>
+     *                            <li>48001 - api功能未授权</li>
+     *                            <li>45009 - 调用接口的QPS超限</li>
+     *                            <li>其他业务错误码</li>
+     *                          </ul>
+     * @see #massGroupMessageSend(WxMpMassTagMessage)
+     * @see #massOpenIdsMessageSend(WxMpMassOpenIdsMessage)
+     * @see <a href="http://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1421140549">上传群发用的视频</a>
     */
    WxMpMassUploadResult massVideoUpload(WxMpMassVideo video) throws WxErrorException;

    /**
     * <pre>
-     * 分组群发消息.
+     * 分组群发消息
     * 如果发送图文消息，必须先使用 {@link #massNewsUpload(WxMpMassNews)} 获得media_id，然后再发送
     * 如果发送视频消息，必须先使用 {@link #massVideoUpload(WxMpMassVideo)} 获得media_id，然后再发送
-     * 详情请见: http://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1421140549&token=&lang=zh_CN
     * </pre>
     *
-     * @param message the message
-     * @return the wx mp mass send result
-     * @throws WxErrorException the wx error exception
+     * @param message 分组群发消息对象
+     * @return 群发结果对象，包含msg_id等信息
+     * @throws WxErrorException 微信API调用异常，可能包括：
+     *                          <ul>
+     *                            <li>40001 - 获取access_token时AppSecret错误，或者access_token无效</li>
+     *                            <li>40002 - 请确保grant_type字段值为client_credential</li>
+     *                            <li>40003 - appid对应公众号请开发者使用绑定的公众号测试</li>
+     *                            <li>40004 - appid不正确</li>
+     *                            <li>40006 - access_token超时</li>
+     *                            <li>48001 - api功能未授权</li>
+     *                            <li>45009 - 调用接口的QPS超限</li>
+     *                            <li>其他业务错误码</li>
+     *                          </ul>
+     * @see <a href="http://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1421140549">分组群发消息</a>
     */
    WxMpMassSendResult massGroupMessageSend(WxMpMassTagMessage message) throws WxErrorException;

    /**
     * <pre>
-     * 按openId列表群发消息.
+     * 按openId列表群发消息
     * 如果发送图文消息，必须先使用 {@link #massNewsUpload(WxMpMassNews)} 获得media_id，然后再发送
     * 如果发送视频消息，必须先使用 {@link #massVideoUpload(WxMpMassVideo)} 获得media_id，然后再发送
-     * 详情请见: http://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1421140549&token=&lang=zh_CN
     * </pre>
     *
-     * @param message the message
-     * @return the wx mp mass send result
-     * @throws WxErrorException the wx error exception
+     * @param message 按openid列表群发消息对象
+     * @return 群发结果对象，包含msg_id等信息
+     * @throws WxErrorException 微信API调用异常，可能包括：
+     *                          <ul>
+     *                            <li>40001 - 获取access_token时AppSecret错误，或者access_token无效</li>
+     *                            <li>40002 - 请确保grant_type字段值为client_credential</li>
+     *                            <li>40003 - appid对应公众号请开发者使用绑定的公众号测试</li>
+     *                            <li>40004 - appid不正确</li>
+     *                            <li>40006 - access_token超时</li>
+     *                            <li>48001 - api功能未授权</li>
+     *                            <li>45009 - 调用接口的QPS超限</li>
+     *                            <li>其他业务错误码</li>
+     *                          </ul>
+     * @see <a href="http://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1421140549">按openId列表群发消息</a>
     */
    WxMpMassSendResult massOpenIdsMessageSend(WxMpMassOpenIdsMessage message) throws WxErrorException;

    /**
     * <pre>
-     * 群发消息预览接口.
+     * 群发消息预览接口
     * 开发者可通过该接口发送消息给指定用户，在手机端查看消息的样式和排版。为了满足第三方平台开发者的需求，
     * 在保留对openID预览能力的同时，增加了对指定微信号发送预览的能力，但该能力每日调用次数有限制（100次），请勿滥用。
-     * 接口调用请求说明
-     *  http请求方式: POST
-     *  https://api.weixin.qq.com/cgi-bin/message/mass/preview?access_token=ACCESS_TOKEN
-     * 详情请见：http://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1421140549&token=&lang=zh_CN
     * </pre>
     *
-     * @param wxMpMassPreviewMessage the wx mp mass preview message
-     * @return wxMpMassSendResult wx mp mass send result
-     * @throws WxErrorException the wx error exception
+     * @param wxMpMassPreviewMessage 预览消息对象
+     * @return 群发结果对象，包含msg_id等信息
+     * @throws WxErrorException 微信API调用异常，可能包括：
+     *                          <ul>
+     *                            <li>40001 - 获取access_token时AppSecret错误，或者access_token无效</li>
+     *                            <li>40002 - 请确保grant_type字段值为client_credential</li>
+     *                            <li>40003 - appid对应公众号请开发者使用绑定的公众号测试</li>
+     *                            <li>40004 - appid不正确</li>
+     *                            <li>40006 - access_token超时</li>
+     *                            <li>48001 - api功能未授权</li>
+     *                            <li>45009 - 调用接口的QPS超限</li>
+     *                            <li>其他业务错误码</li>
+     *                          </ul>
+     * @see <a href="http://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1421140549">群发消息预览接口</a>
     */
    WxMpMassSendResult massMessagePreview(WxMpMassPreviewMessage wxMpMassPreviewMessage) throws WxErrorException;

    /**
     * <pre>
-     * 删除群发.
+     * 删除群发
     * 群发之后，随时可以通过该接口删除群发。
     * 请注意：
     * 1、只有已经发送成功的消息才能删除
     * 2、删除消息是将消息的图文详情页失效，已经收到的用户，还是能在其本地看到消息卡片。
     * 3、删除群发消息只能删除图文消息和视频消息，其他类型的消息一经发送，无法删除。
     * 4、如果多次群发发送的是一个图文消息，那么删除其中一次群发，就会删除掉这个图文消息也，导致所有群发都失效
-     * 接口调用请求说明：
-     *  http请求方式: POST
-     *  https://api.weixin.qq.com/cgi-bin/message/mass/delete?access_token=ACCESS_TOKEN
-     * 详情请见：https://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1481187827_i0l21
     * </pre>
     *
     * @param msgId        发送出去的消息ID
     * @param articleIndex 要删除的文章在图文消息中的位置，第一篇编号为1，该字段不填或填0会删除全部文章
-     * @throws WxErrorException the wx error exception
+     * @throws WxErrorException 微信API调用异常，可能包括：
+     *                          <ul>
+     *                            <li>40001 - 获取access_token时AppSecret错误，或者access_token无效</li>
+     *                            <li>40002 - 请确保grant_type字段值为client_credential</li>
+     *                            <li>40003 - appid对应公众号请开发者使用绑定的公众号测试</li>
+     *                            <li>40004 - appid不正确</li>
+     *                            <li>40006 - access_token超时</li>
+     *                            <li>48001 - api功能未授权</li>
+     *                            <li>45009 - 调用接口的QPS超限</li>
+     *                            <li>其他业务错误码</li>
+     *                          </ul>
+     * @see <a href="https://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1481187827_i0l21">删除群发</a>
     */
    void delete(Long msgId, Integer articleIndex) throws WxErrorException;

-
    /**
+     * <pre>
     * 获取群发速度
-     * https://developers.weixin.qq.com/doc/offiaccount/Message_Management/Batch_Sends_and_Originality_Checks.html#9
+     * </pre>
     *
-     * @return the wx mp mass speed get result
-     * @throws WxErrorException the wx error exception
+     * @return 群发速度获取结果对象
+     * @throws WxErrorException 微信API调用异常，可能包括：
+     *                          <ul>
+     *                            <li>40001 - 获取access_token时AppSecret错误，或者access_token无效</li>
+     *                            <li>40002 - 请确保grant_type字段值为client_credential</li>
+     *                            <li>40003 - appid对应公众号请开发者使用绑定的公众号测试</li>
+     *                            <li>40004 - appid不正确</li>
+     *                            <li>40006 - access_token超时</li>
+     *                            <li>48001 - api功能未授权</li>
+     *                            <li>45009 - 调用接口的QPS超限</li>
+     *                            <li>其他业务错误码</li>
+     *                          </ul>
+     * @see <a href="https://developers.weixin.qq.com/doc/offiaccount/Message_Management/Batch_Sends_and_Originality_Checks.html#9">获取群发速度</a>
     */
    WxMpMassSpeedGetResult messageMassSpeedGet() throws WxErrorException;

-
    /**
+     * <pre>
     * 设置群发速度
-     * https://developers.weixin.qq.com/doc/offiaccount/Message_Management/Batch_Sends_and_Originality_Checks.html#9
+     * </pre>
     *
-     * @param speed 群发速度的级别，是一个0到4的整数，数字越大表示群发速度越慢。              speed	realspeed              0	80w/分钟              1	60w/分钟              2	45w/分钟              3	30w/分钟              4	10w/分钟
-     * @throws WxErrorException the wx error exception
+     * @param speed 群发速度的级别，是一个0到4的整数，数字越大表示群发速度越慢。
+     *              speed	realspeed
+     *              0	80w/分钟
+     *              1	60w/分钟
+     *              2	45w/分钟
+     *              3	30w/分钟
+     *              4	10w/分钟
+     * @throws WxErrorException 微信API调用异常，可能包括：
+     *                          <ul>
+     *                            <li>40001 - 获取access_token时AppSecret错误，或者access_token无效</li>
+     *                            <li>40002 - 请确保grant_type字段值为client_credential</li>
+     *                            <li>40003 - appid对应公众号请开发者使用绑定的公众号测试</li>
+     *                            <li>40004 - appid不正确</li>
+     *                            <li>40006 - access_token超时</li>
+     *                            <li>48001 - api功能未授权</li>
+     *                            <li>45009 - 调用接口的QPS超限</li>
+     *                            <li>其他业务错误码</li>
+     *                          </ul>
+     * @see <a href="https://developers.weixin.qq.com/doc/offiaccount/Message_Management/Batch_Sends_and_Originality_Checks.html#9">设置群发速度</a>
     */
    void messageMassSpeedSet(Integer speed) throws WxErrorException;

-
    /**
+     * <pre>
     * 查询群发消息发送状态【订阅号与服务号认证后均可用】
-     * https://developers.weixin.qq.com/doc/offiaccount/Message_Management/Batch_Sends_and_Originality_Checks.html#%E6%9F%A5%E8%AF%A2%E7%BE%A4%E5%8F%91%E6%B6%88%E6%81%AF%E5%8F%91%E9%80%81%E7%8A%B6%E6%80%81%E3%80%90%E8%AE%A2%E9%98%85%E5%8F%B7%E4%B8%8E%E6%9C%8D%E5%8A%A1%E5%8F%B7%E8%AE%A4%E8%AF%81%E5%90%8E%E5%9D%87%E5%8F%AF%E7%94%A8%E3%80%91
+     * </pre>
     *
     * @param msgId 群发消息后返回的消息id
-     * @return 消息发送后的状态 ，SEND_SUCCESS表示发送成功，SENDING表示发送中，SEND_FAIL表示发送失败，DELETE表示已删除
-     * @throws WxErrorException the wx error exception
+     * @return 消息发送后的状态，SEND_SUCCESS表示发送成功，SENDING表示发送中，SEND_FAIL表示发送失败，DELETE表示已删除
+     * @throws WxErrorException 微信API调用异常，可能包括：
+     *                          <ul>
+     *                            <li>40001 - 获取access_token时AppSecret错误，或者access_token无效</li>
+     *                            <li>40002 - 请确保grant_type字段值为client_credential</li>
+     *                            <li>40003 - appid对应公众号请开发者使用绑定的公众号测试</li>
+     *                            <li>40004 - appid不正确</li>
+     *                            <li>40006 - access_token超时</li>
+     *                            <li>48001 - api功能未授权</li>
+     *                            <li>45009 - 调用接口的QPS超限</li>
+     *                            <li>其他业务错误码</li>
+     *                          </ul>
+     * @see <a href="https://developers.weixin.qq.com/doc/offiaccount/Message_Management/Batch_Sends_and_Originality_Checks.html#%E6%9F%A5%E8%AF%A2%E7%BE%A4%E5%8F%91%E6%B6%88%E6%81%AF%E5%8F%91%E9%80%92%E7%8A%B6%E6%80%81%E3%80%90%E8%AE%A2%E9%98%85%E5%8F%B7%E4%B8%8E%E6%9C%8D%E5%8A%A1%E5%8F%B7%E8%AE%A4%E8%AF%81%E5%90%8E%E5%9D%87%E5%8F%AF%E7%94%A8%E3%80%91">查询群发消息发送状态</a>
     */
    WxMpMassGetResult messageMassGet(Long msgId) throws WxErrorException;
-
 }
--- a/weixin-java-mp/src/main/java/me/chanjar/weixin/mp/api/WxMpMaterialService.java
+++ b/weixin-java-mp/src/main/java/me/chanjar/weixin/mp/api/WxMpMaterialService.java
@@ -17,7 +17,6 @@ import me.chanjar.weixin.mp.bean.material.WxMpMaterialVideoInfoResult;

 /**
 * <pre>
- * Created by Binary Wang on 2016/7/21.
 * 素材管理的相关接口，包括媒体管理的接口，
 * 即以https://api.weixin.qq.com/cgi-bin/material
 * 和 https://api.weixin.qq.com/cgi-bin/media开头的接口
@@ -36,7 +35,7 @@ public interface WxMpMaterialService {
     *  2、media_id是可复用的。
     *  3、素材的格式大小等要求与公众平台官网一致。具体是，图片大小不超过2M，支持png/jpeg/jpg/gif格式，语音大小不超过5M，长度不超过60秒，支持mp3/amr格式
     *  4、需使用https调用本接口。
-     *  本接口即为原“上传多媒体文件”接口。
+     *  本接口即为原"上传多媒体文件"接口。
     *  注意事项：
     *    上传的临时多媒体文件有格式和大小限制，如下：
     *    图片（image）: 2M，支持PNG\JPEG\JPG\GIF格式
@@ -49,17 +48,17 @@ public interface WxMpMaterialService {
     * </pre>
     *
     * @param mediaType 媒体类型, 请看{@link me.chanjar.weixin.common.api.WxConsts}
-     * @param file      文件对象
-     * @return the wx media upload result
-     * @throws WxErrorException the wx error exception
-     * @see #mediaUpload(String, String, InputStream) #mediaUpload(String, String, InputStream)#mediaUpload(String, String, InputStream)
+     * @param file      文件对象，需要上传的临时素材文件
+     * @return 上传结果，包含media_id等信息
+     * @throws WxErrorException 微信API调用异常
+     * @see #mediaUpload(String, String, InputStream) 使用输入流上传临时素材
     */
    WxMediaUploadResult mediaUpload(String mediaType, File file) throws WxErrorException;

    /**
     * <pre>
     * 新增临时素材
-     * 本接口即为原“上传多媒体文件”接口。
+     * 本接口即为原"上传多媒体文件"接口。
     *
     * 详情请见: <a href="http://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1444738726&token=&lang=zh_CN">新增临时素材</a>
     * 接口url格式：https://api.weixin.qq.com/cgi-bin/media/upload?access_token=ACCESS_TOKEN&type=TYPE
@@ -67,10 +66,10 @@ public interface WxMpMaterialService {
     *
     * @param mediaType   媒体类型, 请看{@link me.chanjar.weixin.common.api.WxConsts}
     * @param fileType    文件类型，请看{@link me.chanjar.weixin.common.api.WxConsts}
-     * @param inputStream 输入流
-     * @return the wx media upload result
-     * @throws WxErrorException the wx error exception
-     * @see #mediaUpload(java.lang.String, java.io.File) #mediaUpload(java.lang.String, java.io.File)#mediaUpload(java.lang.String, java.io.File)
+     * @param inputStream 输入流，包含要上传的临时素材内容
+     * @return 上传结果，包含media_id等信息
+     * @throws WxErrorException 微信API调用异常
+     * @see #mediaUpload(String, File) 使用文件对象上传临时素材
     */
    WxMediaUploadResult mediaUpload(String mediaType, String fileType, InputStream inputStream) throws WxErrorException;

@@ -78,15 +77,15 @@ public interface WxMpMaterialService {
     * <pre>
     * 获取临时素材
     * 公众号可以使用本接口获取临时素材（即下载临时的多媒体文件）。请注意，视频文件不支持https下载，调用该接口需http协议。
-     * 本接口即为原“下载多媒体文件”接口。
+     * 本接口即为原"下载多媒体文件"接口。
     * 根据微信文档，视频文件下载不了，会返回null
     * 详情请见: <a href="http://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1444738727&token=&lang=zh_CN">获取临时素材</a>
     * 接口url格式：https://api.weixin.qq.com/cgi-bin/media/get?access_token=ACCESS_TOKEN&media_id=MEDIA_ID
     * </pre>
     *
-     * @param mediaId 媒体文件Id
-     * @return 保存到本地的临时文件 file
-     * @throws WxErrorException the wx error exception
+     * @param mediaId 媒体文件Id，通过上传临时素材接口获取
+     * @return 保存到本地的临时文件，如果下载失败则返回null
+     * @throws WxErrorException 微信API调用异常
     */
    File mediaDownload(String mediaId) throws WxErrorException;

@@ -100,9 +99,9 @@ public interface WxMpMaterialService {
     * 接口url格式：https://api.weixin.qq.com/cgi-bin/media/get/jssdk?access_token=ACCESS_TOKEN&media_id=MEDIA_ID
     * </pre>
     *
-     * @param mediaId 媒体文件Id
-     * @return 保存到本地的临时文件 file
-     * @throws WxErrorException the wx error exception
+     * @param mediaId 媒体文件Id，通过JSSDK上传语音素材获取
+     * @return 保存到本地的临时文件，高清语音素材
+     * @throws WxErrorException 微信API调用异常
     */
    File jssdkMediaDownload(String mediaId) throws WxErrorException;

@@ -114,9 +113,9 @@ public interface WxMpMaterialService {
     * 接口url格式：https://api.weixin.qq.com/cgi-bin/media/uploadimg?access_token=ACCESS_TOKEN
     * </pre>
     *
-     * @param file 上传的文件对象
-     * @return WxMediaImgUploadResult 返回图片url
-     * @throws WxErrorException the wx error exception
+     * @param file 上传的文件对象，图片素材，支持jpg/png格式，大小不超过1MB
+     * @return 图片上传结果，包含图片URL，可用于图文消息中
+     * @throws WxErrorException 微信API调用异常
     */
    WxMediaImgUploadResult mediaImgUpload(File file) throws WxErrorException;

@@ -141,8 +140,8 @@ public interface WxMpMaterialService {
     *
     * @param mediaType 媒体类型, 请看{@link me.chanjar.weixin.common.api.WxConsts}
     * @param material  上传的素材, 请看{@link WxMpMaterial}
-     * @return the wx mp material upload result
-     * @throws WxErrorException the wx error exception
+     * @return 上传结果，包含media_id等信息
+     * @throws WxErrorException 微信API调用异常
     */
    WxMpMaterialUploadResult materialFileUpload(String mediaType, WxMpMaterial material) throws WxErrorException;

@@ -155,8 +154,8 @@ public interface WxMpMaterialService {
     * </pre>
     *
     * @param mediaId 永久素材的id
-     * @return the input stream
-     * @throws WxErrorException the wx error exception
+     * @return 素材内容的输入流，可用于读取图片或语音文件
+     * @throws WxErrorException 微信API调用异常
     */
    InputStream materialImageOrVoiceDownload(String mediaId) throws WxErrorException;

@@ -169,8 +168,8 @@ public interface WxMpMaterialService {
     * </pre>
     *
     * @param mediaId 永久素材的id
-     * @return the wx mp material video info result
-     * @throws WxErrorException the wx error exception
+     * @return 视频素材信息，包含标题、描述和下载地址
+     * @throws WxErrorException 微信API调用异常
     */
    WxMpMaterialVideoInfoResult materialVideoInfo(String mediaId) throws WxErrorException;

@@ -183,8 +182,8 @@ public interface WxMpMaterialService {
     * </pre>
     *
     * @param mediaId 永久素材的id
-     * @return the wx mp material news
-     * @throws WxErrorException the wx error exception
+     * @return 图文素材信息，包含文章列表和标题等
+     * @throws WxErrorException 微信API调用异常
     */
    WxMpMaterialNews materialNewsInfo(String mediaId) throws WxErrorException;

@@ -201,8 +200,8 @@ public interface WxMpMaterialService {
     * </pre>
     *
     * @param mediaId 永久素材的id
-     * @return the boolean
-     * @throws WxErrorException the wx error exception
+     * @return 删除是否成功，true表示成功，false表示失败
+     * @throws WxErrorException 微信API调用异常
     */
    boolean materialDelete(String mediaId) throws WxErrorException;

@@ -219,8 +218,8 @@ public interface WxMpMaterialService {
     * 接口url格式：https://api.weixin.qq.com/cgi-bin/material/get_materialcount?access_token=ACCESS_TOKEN
     * </pre>
     *
-     * @return the wx mp material count result
-     * @throws WxErrorException the wx error exception
+     * @return 素材统计结果，包含各类素材的数量
+     * @throws WxErrorException 微信API调用异常
     */
    WxMpMaterialCountResult materialCount() throws WxErrorException;

@@ -232,10 +231,10 @@ public interface WxMpMaterialService {
     * 接口url格式：https://api.weixin.qq.com/cgi-bin/material/batchget_material?access_token=ACCESS_TOKEN
     * </pre>
     *
-     * @param offset 从全部素材的该偏移位置开始返回，0表示从第一个素材 返回
+     * @param offset 从全部素材的该偏移位置开始返回，0表示从第一个素材返回
     * @param count  返回素材的数量，取值在1到20之间
-     * @return the wx mp material news batch get result
-     * @throws WxErrorException the wx error exception
+     * @return 图文素材列表，包含文章列表和标题等信息
+     * @throws WxErrorException 微信API调用异常
     */
    WxMpMaterialNewsBatchGetResult materialNewsBatchGet(int offset, int count) throws WxErrorException;

@@ -248,10 +247,10 @@ public interface WxMpMaterialService {
     * </pre>
     *
     * @param type   媒体类型, 请看{@link me.chanjar.weixin.common.api.WxConsts}
-     * @param offset 从全部素材的该偏移位置开始返回，0表示从第一个素材 返回
+     * @param offset 从全部素材的该偏移位置开始返回，0表示从第一个素材返回
     * @param count  返回素材的数量，取值在1到20之间
-     * @return the wx mp material file batch get result
-     * @throws WxErrorException the wx error exception
+     * @return 其他媒体素材列表，包含图片、语音、视频等素材信息
+     * @throws WxErrorException 微信API调用异常
     */
    WxMpMaterialFileBatchGetResult materialFileBatchGet(String type, int offset, int count) throws WxErrorException;

--- a/weixin-java-mp/src/main/java/me/chanjar/weixin/mp/api/WxMpMenuService.java
+++ b/weixin-java-mp/src/main/java/me/chanjar/weixin/mp/api/WxMpMenuService.java
@@ -19,9 +19,9 @@ public interface WxMpMenuService {
     * 详情请见：https://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1455782296&token=&lang=zh_CN
     * </pre>
     *
-     * @param menu the menu
-     * @return 如果是个性化菜单 ，则返回menuid，否则返回null
-     * @throws WxErrorException the wx error exception
+     * @param menu 菜单对象，包含菜单结构和配置信息
+     * @return 如果是个性化菜单，则返回menuid，否则返回null
+     * @throws WxErrorException 微信API调用异常
     */
    String menuCreate(WxMenu menu) throws WxErrorException;

@@ -33,9 +33,9 @@ public interface WxMpMenuService {
     * 详情请见：https://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1455782296&token=&lang=zh_CN
     * </pre>
     *
-     * @param json the json
-     * @return 如果是个性化菜单 ，则返回menuid，否则返回null
-     * @throws WxErrorException the wx error exception
+     * @param json 菜单配置的JSON字符串，包含菜单结构和配置信息
+     * @return 如果是个性化菜单，则返回menuid，否则返回null
+     * @throws WxErrorException 微信API调用异常
     */
    String menuCreate(String json) throws WxErrorException;

@@ -45,7 +45,7 @@ public interface WxMpMenuService {
     * 详情请见: https://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1421141015&token=&lang=zh_CN
     * </pre>
     *
-     * @throws WxErrorException the wx error exception
+     * @throws WxErrorException 微信API调用异常
     */
    void menuDelete() throws WxErrorException;

@@ -55,8 +55,8 @@ public interface WxMpMenuService {
     * 详情请见: https://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1455782296&token=&lang=zh_CN
     * </pre>
     *
-     * @param menuId 个性化菜单的menuid
-     * @throws WxErrorException the wx error exception
+     * @param menuId 个性化菜单的menuid，通过创建个性化菜单时返回
+     * @throws WxErrorException 微信API调用异常
     */
    void menuDelete(String menuId) throws WxErrorException;

@@ -66,8 +66,8 @@ public interface WxMpMenuService {
     * 详情请见： https://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1421141014&token=&lang=zh_CN
     * </pre>
     *
-     * @return the wx mp menu
-     * @throws WxErrorException the wx error exception
+     * @return 当前公众号的自定义菜单配置
+     * @throws WxErrorException 微信API调用异常
     */
    WxMpMenu menuGet() throws WxErrorException;

@@ -77,9 +77,9 @@ public interface WxMpMenuService {
     * 详情请见: http://mp.weixin.qq.com/wiki/0/c48ccd12b69ae023159b4bfaa7c39c20.html
     * </pre>
     *
-     * @param userid 可以是粉丝的OpenID，也可以是粉丝的微信号。
-     * @return the wx menu
-     * @throws WxErrorException the wx error exception
+     * @param userid 可以是粉丝的OpenID，也可以是粉丝的微信号
+     * @return 匹配到的菜单配置
+     * @throws WxErrorException 微信API调用异常
     */
    WxMenu menuTryMatch(String userid) throws WxErrorException;

@@ -98,8 +98,8 @@ public interface WxMpMenuService {
     * https://api.weixin.qq.com/cgi-bin/get_current_selfmenu_info?access_token=ACCESS_TOKEN
     * </pre>
     *
-     * @return the self menu info
-     * @throws WxErrorException the wx error exception
+     * @return 自定义菜单配置信息，包含菜单结构和配置详情
+     * @throws WxErrorException 微信API调用异常
     */
    WxMpGetSelfMenuInfoResult getSelfMenuInfo() throws WxErrorException;
 }
--- a/weixin-java-mp/src/main/java/me/chanjar/weixin/mp/api/WxMpQrcodeService.java
+++ b/weixin-java-mp/src/main/java/me/chanjar/weixin/mp/api/WxMpQrcodeService.java
@@ -22,8 +22,8 @@ public interface WxMpQrcodeService {
     *
     * @param sceneId       场景值ID，临时二维码时为32位非0整型
     * @param expireSeconds 该二维码有效时间，以秒为单位。 最大不超过2592000（即30天），此字段如果不填，则默认有效期为30秒。
-     * @return the wx mp qr code ticket
-     * @throws WxErrorException the wx error exception
+     * @return 二维码ticket，可用于获取二维码图片
+     * @throws WxErrorException 微信API调用异常
     */
    WxMpQrCodeTicket qrCodeCreateTmpTicket(int sceneId, Integer expireSeconds) throws WxErrorException;

@@ -36,8 +36,8 @@ public interface WxMpQrcodeService {
     *
     * @param sceneStr      场景值ID（字符串形式的ID），字符串类型，长度限制为1到64
     * @param expireSeconds 该二维码有效时间，以秒为单位。 最大不超过2592000（即30天），此字段如果不填，则默认有效期为30秒。
-     * @return the wx mp qr code ticket
-     * @throws WxErrorException the wx error exception
+     * @return 二维码ticket，可用于获取二维码图片
+     * @throws WxErrorException 微信API调用异常
     */
    WxMpQrCodeTicket qrCodeCreateTmpTicket(String sceneStr, Integer expireSeconds) throws WxErrorException;

@@ -48,8 +48,8 @@ public interface WxMpQrcodeService {
     * </pre>
     *
     * @param sceneId 场景值ID，最大值为100000（目前参数只支持1--100000）
-     * @return the wx mp qr code ticket
-     * @throws WxErrorException the wx error exception
+     * @return 二维码ticket，可用于获取二维码图片
+     * @throws WxErrorException 微信API调用异常
     */
    WxMpQrCodeTicket qrCodeCreateLastTicket(int sceneId) throws WxErrorException;

@@ -60,8 +60,8 @@ public interface WxMpQrcodeService {
     * </pre>
     *
     * @param sceneStr 参数。字符串类型长度现在为1到64
-     * @return the wx mp qr code ticket
-     * @throws WxErrorException the wx error exception
+     * @return 二维码ticket，可用于获取二维码图片
+     * @throws WxErrorException 微信API调用异常
     */
    WxMpQrCodeTicket qrCodeCreateLastTicket(String sceneStr) throws WxErrorException;

@@ -71,9 +71,9 @@ public interface WxMpQrcodeService {
     * 详情请见: <a href="https://mp.weixin.qq.com/wiki?action=doc&id=mp1443433542&t=0.9274944716856435">生成带参数的二维码</a>
     * </pre>
     *
-     * @param ticket 二维码ticket
-     * @return the file
-     * @throws WxErrorException the wx error exception
+     * @param ticket 二维码ticket，通过创建二维码接口获取
+     * @return 二维码图片文件，jpg格式
+     * @throws WxErrorException 微信API调用异常
     */
    File qrCodePicture(WxMpQrCodeTicket ticket) throws WxErrorException;

@@ -85,8 +85,9 @@ public interface WxMpQrcodeService {
     *
     * @param ticket       二维码ticket
     * @param needShortUrl 是否需要压缩的二维码地址
-     * @return the string
-     * @throws WxErrorException the wx error exception
+     * @return 二维码图片的URL地址
+     * @throws WxErrorException 微信API调用异常
+     * @deprecated 请使用 {@link #qrCodePictureUrl(String)} 方法
     */
    @Deprecated
    String qrCodePictureUrl(String ticket, boolean needShortUrl) throws WxErrorException;
@@ -97,9 +98,9 @@ public interface WxMpQrcodeService {
     * 详情请见: <a href="https://mp.weixin.qq.com/wiki?action=doc&id=mp1443433542&t=0.9274944716856435">生成带参数的二维码</a>
     * </pre>
     *
-     * @param ticket 二维码ticket
-     * @return the string
-     * @throws WxErrorException the wx error exception
+     * @param ticket 二维码ticket，通过创建二维码接口获取
+     * @return 二维码图片的URL地址
+     * @throws WxErrorException 微信API调用异常
     */
    String qrCodePictureUrl(String ticket) throws WxErrorException;

--- a/weixin-java-mp/src/main/java/me/chanjar/weixin/mp/api/WxMpService.java
+++ b/weixin-java-mp/src/main/java/me/chanjar/weixin/mp/api/WxMpService.java
@@ -37,7 +37,7 @@ public interface WxMpService extends WxService {
   * @param longData      需要转换的长信息，不超过4KB
   * @param expireSeconds 短key有效期(单位秒)，最大值为2592000（即30天），默认为2592000(30天)
   * @return shortKey 短key，15字节，base62编码(0-9/a-z/A-Z)
-   * @throws WxErrorException .
+   * @throws WxErrorException 微信API调用异常
   */
  String genShorten(String longData, Integer expireSeconds) throws WxErrorException;

@@ -47,9 +47,9 @@ public interface WxMpService extends WxService {
   * 详情请见: https://developers.weixin.qq.com/doc/offiaccount/Account_Management/KEY_Shortener.html
   * </pre>
   *
-   * @param shortKey 短key
-   * @return WxMpShortKeyResult 解析结果
-   * @throws WxErrorException .
+   * @param shortKey 短key，15字节，base62编码(0-9/a-z/A-Z)
+   * @return WxMpShortKeyResult 解析结果，包含原始长信息
+   * @throws WxErrorException 微信API调用异常
   */
  WxMpShortKeyResult fetchShorten(String shortKey) throws WxErrorException;

@@ -59,19 +59,19 @@ public interface WxMpService extends WxService {
   * 详情请见: http://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1421135319&token=&lang=zh_CN
   * </pre>
   *
-   * @param timestamp 时间戳
-   * @param nonce     随机串
-   * @param signature 签名
-   * @return 是否验证通过 boolean
+   * @param timestamp 时间戳，字符串格式
+   * @param nonce     随机串，字符串格式
+   * @param signature 签名，字符串格式
+   * @return 是否验证通过，true表示验证通过，false表示验证失败
   */
  boolean checkSignature(String timestamp, String nonce, String signature);

  /**
   * 获取access_token, 不强制刷新access_token.
   *
-   * @return token access token
-   * @throws WxErrorException .
-   * @see #getAccessToken(boolean) #getAccessToken(boolean)#getAccessToken(boolean)#getAccessToken(boolean)
+   * @return token access token，字符串格式
+   * @throws WxErrorException 微信API调用异常
+   * @see #getAccessToken(boolean) 获取access_token，可选择是否强制刷新
   */
  String getAccessToken() throws WxErrorException;

@@ -87,21 +87,21 @@ public interface WxMpService extends WxService {
   * 详情请见: http://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1421140183&token=&lang=zh_CN
   * </pre>
   *
-   * @param forceRefresh 是否强制刷新
-   * @return token access token
-   * @throws WxErrorException .
+   * @param forceRefresh 是否强制刷新，true表示强制刷新，false表示使用缓存
+   * @return token access token，字符串格式
+   * @throws WxErrorException 微信API调用异常
   */
  String getAccessToken(boolean forceRefresh) throws WxErrorException;

  /**
   * 获得ticket,不强制刷新ticket.
   *
-   * @param type ticket 类型
-   * @return ticket ticket
-   * @throws WxErrorException .
-   * @see #getTicket(TicketType, boolean) #getTicket(TicketType, boolean)#getTicket(TicketType, boolean)#getTicket(TicketType, boolean)
+   * @param ticketType ticket 类型，通过TicketType枚举指定
+   * @return ticket ticket，字符串格式
+   * @throws WxErrorException 微信API调用异常
+   * @see #getTicket(TicketType, boolean) 获得ticket，可选择是否强制刷新
   */
-  String getTicket(TicketType type) throws WxErrorException;
+  String getTicket(TicketType ticketType) throws WxErrorException;

  /**
   * <pre>
@@ -109,19 +109,19 @@ public interface WxMpService extends WxService {
   * 获得时会检查 Token是否过期，如果过期了，那么就刷新一下，否则就什么都不干
   * </pre>
   *
-   * @param type         ticket类型
-   * @param forceRefresh 强制刷新
-   * @return ticket ticket
-   * @throws WxErrorException .
+   * @param ticketType   ticket类型，通过TicketType枚举指定
+   * @param forceRefresh 强制刷新，true表示强制刷新，false表示使用缓存
+   * @return ticket ticket，字符串格式
+   * @throws WxErrorException 微信API调用异常
   */
-  String getTicket(TicketType type, boolean forceRefresh) throws WxErrorException;
+  String getTicket(TicketType ticketType, boolean forceRefresh) throws WxErrorException;

  /**
   * 获得jsapi_ticket,不强制刷新jsapi_ticket.
   *
-   * @return jsapi ticket
-   * @throws WxErrorException .
-   * @see #getJsapiTicket(boolean) #getJsapiTicket(boolean)#getJsapiTicket(boolean)#getJsapiTicket(boolean)
+   * @return jsapi ticket，字符串格式
+   * @throws WxErrorException 微信API调用异常
+   * @see #getJsapiTicket(boolean) 获得jsapi_ticket，可选择是否强制刷新
   */
  String getJsapiTicket() throws WxErrorException;

@@ -133,9 +133,9 @@ public interface WxMpService extends WxService {
   * 详情请见：http://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1421141115&token=&lang=zh_CN
   * </pre>
   *
-   * @param forceRefresh 强制刷新
-   * @return jsapi ticket
-   * @throws WxErrorException .
+   * @param forceRefresh 强制刷新，true表示强制刷新，false表示使用缓存
+   * @return jsapi ticket，字符串格式
+   * @throws WxErrorException 微信API调用异常
   */
  String getJsapiTicket(boolean forceRefresh) throws WxErrorException;

@@ -146,9 +146,9 @@ public interface WxMpService extends WxService {
   * 详情请见：http://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1421141115&token=&lang=zh_CN
   * </pre>
   *
-   * @param url 地址
-   * @return 生成的签名对象 wx jsapi signature
-   * @throws WxErrorException .
+   * @param url 当前网页的URL，不包括#及其后面部分
+   * @return 生成的签名对象，包含签名、时间戳、随机串等信息
+   * @throws WxErrorException 微信API调用异常
   */
  WxJsapiSignature createJsapiSignature(String url) throws WxErrorException;

@@ -158,9 +158,10 @@ public interface WxMpService extends WxService {
   * 详情请见: http://mp.weixin.qq.com/wiki/index.php?title=长链接转短链接接口
   * </pre>
   *
-   * @param longUrl 长url
-   * @return 生成的短地址 string
-   * @throws WxErrorException .
+   * @param longUrl 长url，需要转换的原始URL
+   * @return 生成的短地址，字符串格式
+   * @throws WxErrorException 微信API调用异常
+   * @deprecated 请使用 {@link #genShorten(String, Integer)} 方法
   */
  @Deprecated
  String shortUrl(String longUrl) throws WxErrorException;
@@ -171,9 +172,9 @@ public interface WxMpService extends WxService {
   * 详情请见：http://mp.weixin.qq.com/wiki/index.php?title=语义理解
   * </pre>
   *
-   * @param semanticQuery 查询条件
-   * @return 查询结果 wx mp semantic query result
-   * @throws WxErrorException .
+   * @param semanticQuery 查询条件，包含查询内容、类型等信息
+   * @return 查询结果，包含语义理解的结果和建议回复
+   * @throws WxErrorException 微信API调用异常
   */
  WxMpSemanticQueryResult semanticQuery(WxMpSemanticQuery semanticQuery) throws WxErrorException;

@@ -187,7 +188,7 @@ public interface WxMpService extends WxService {
   * @param redirectUri 用户授权完成后的重定向链接，无需urlencode, 方法内会进行encode
   * @param scope       应用授权作用域，拥有多个作用域用逗号（,）分隔，网页应用目前仅填写snsapi_login即可
   * @param state       非必填，用于保持请求和回调的状态，授权请求后原样带回给第三方。该参数可用于防止csrf攻击（跨站请求伪造攻击），建议第三方带上该参数，可设置为简单的随机数加session进行校验
-   * @return url string
+   * @return url 构造好的授权登录URL，字符串格式
   */
  String buildQrConnectUrl(String redirectUri, String scope, String state);

@@ -197,8 +198,8 @@ public interface WxMpService extends WxService {
   * http://mp.weixin.qq.com/wiki/0/2ad4b6bfd29f30f71d39616c2a0fcedc.html
   * </pre>
   *
-   * @return 微信服务器ip地址数组 string [ ]
-   * @throws WxErrorException .
+   * @return 微信服务器ip地址数组，包含所有微信服务器IP地址
+   * @throws WxErrorException 微信API调用异常
   */
  String[] getCallbackIP() throws WxErrorException;

@@ -209,10 +210,10 @@ public interface WxMpService extends WxService {
   *  为了帮助开发者排查回调连接失败的问题，提供这个网络检测的API。它可以对开发者URL做域名解析，然后对所有IP进行一次ping操作，得到丢包率和耗时。
   * </pre>
   *
-   * @param action   执行的检测动作
-   * @param operator 指定平台从某个运营商进行检测
-   * @return 检测结果 wx net check result
-   * @throws WxErrorException .
+   * @param action   执行的检测动作，可选值：all（全部检测）、dns（仅域名解析）、ping（仅网络连通性检测）
+   * @param operator 指定平台从某个运营商进行检测，可选值：CHINANET（中国电信）、UNICOM（中国联通）、CAP（中国联通）、CUCC（中国联通）
+   * @return 检测结果，包含丢包率和耗时等信息
+   * @throws WxErrorException 微信API调用异常
   */
  WxNetCheckResult netCheck(String action, String operator) throws WxErrorException;

@@ -232,8 +233,8 @@ public interface WxMpService extends WxService {
   * https://api.weixin.qq.com/cgi-bin/get_current_autoreply_info?access_token=ACCESS_TOKEN
   * </pre>
   *
-   * @return 公众号的自动回复规则 current auto reply info
-   * @throws WxErrorException .
+   * @return 公众号的自动回复规则，包含关注后自动回复、消息自动回复、关键词自动回复等信息
+   * @throws WxErrorException 微信API调用异常
   */
  WxMpCurrentAutoReplyInfo getCurrentAutoReplyInfo() throws WxErrorException;

@@ -245,8 +246,8 @@ public interface WxMpService extends WxService {
   *
   * </pre>
   *
-   * @param appid 公众号的APPID
-   * @throws WxErrorException the wx error exception
+   * @param appid 公众号的APPID，需要清零调用的公众号的appid
+   * @throws WxErrorException 微信API调用异常
   */
  void clearQuota(String appid) throws WxErrorException;

@@ -257,53 +258,53 @@ public interface WxMpService extends WxService {
   * 可以参考，{@link MediaUploadRequestExecutor}的实现方法
   * </pre>
   *
-   * @param <T>      the type parameter
-   * @param <E>      the type parameter
-   * @param executor 执行器
-   * @param url      接口地址
-   * @param data     参数数据
-   * @return 结果 t
-   * @throws WxErrorException 异常
+   * @param <T>      返回值类型
+   * @param <E>      参数类型
+   * @param executor 执行器，用于处理请求和响应
+   * @param url      接口地址，字符串格式
+   * @param data     参数数据，根据API不同可能是不同类型
+   * @return 结果，根据API不同可能是不同类型
+   * @throws WxErrorException 微信API调用异常
   */
  <T, E> T execute(RequestExecutor<T, E> executor, String url, E data) throws WxErrorException;

  /**
   * 当本Service没有实现某个API的时候，可以用这个，针对所有微信API中的GET请求.
   *
-   * @param url        请求接口地址
-   * @param queryParam 参数
-   * @return 接口响应字符串 string
-   * @throws WxErrorException 异常
+   * @param url        请求接口地址，通过WxMpApiUrl枚举指定
+   * @param queryParam 参数，字符串格式，通常是URL查询参数
+   * @return 接口响应字符串，JSON格式
+   * @throws WxErrorException 微信API调用异常
   */
  String get(WxMpApiUrl url, String queryParam) throws WxErrorException;

  /**
   * 当本Service没有实现某个API的时候，可以用这个，针对所有微信API中的POST请求.
   *
-   * @param url      请求接口地址
-   * @param postData 请求参数json值
-   * @return 接口响应字符串 string
-   * @throws WxErrorException 异常
+   * @param url      请求接口地址，通过WxMpApiUrl枚举指定
+   * @param postData 请求参数json值，字符串格式
+   * @return 接口响应字符串，JSON格式
+   * @throws WxErrorException 微信API调用异常
   */
  String post(WxMpApiUrl url, String postData) throws WxErrorException;

  /**
   * 当本Service没有实现某个API的时候，可以用这个，针对所有微信API中的POST请求.
   *
-   * @param url 请求接口地址
-   * @param obj 请求参数
-   * @return 接口响应字符串 string
-   * @throws WxErrorException 异常
+   * @param url 请求接口地址，通过WxMpApiUrl枚举指定
+   * @param obj 请求参数，对象格式，会被序列化为JSON
+   * @return 接口响应字符串，JSON格式
+   * @throws WxErrorException 微信API调用异常
   */
  String post(WxMpApiUrl url, Object obj) throws WxErrorException;

  /**
   * 当本Service没有实现某个API的时候，可以用这个，针对所有微信API中的POST请求.
   *
-   * @param url        请求接口地址
-   * @param jsonObject 请求参数json对象
-   * @return 接口响应字符串 string
-   * @throws WxErrorException 异常
+   * @param url        请求接口地址，通过WxMpApiUrl枚举指定
+   * @param jsonObject 请求参数json对象，JSON格式
+   * @return 接口响应字符串，JSON格式
+   * @throws WxErrorException 微信API调用异常
   */
  String post(WxMpApiUrl url, JsonObject jsonObject) throws WxErrorException;

@@ -314,20 +315,20 @@ public interface WxMpService extends WxService {
   * 可以参考，{@link MediaUploadRequestExecutor}的实现方法
   * </pre>
   *
-   * @param <T>      the type parameter
-   * @param <E>      the type parameter
-   * @param executor 执行器
-   * @param url      接口地址
-   * @param data     参数数据
-   * @return 结果 t
-   * @throws WxErrorException 异常
+   * @param <T>      返回值类型
+   * @param <E>      参数类型
+   * @param executor 执行器，用于处理请求和响应
+   * @param url      接口地址，通过WxMpApiUrl枚举指定
+   * @param data     参数数据，根据API不同可能是不同类型
+   * @return 结果，根据API不同可能是不同类型
+   * @throws WxErrorException 微信API调用异常
   */
  <T, E> T execute(RequestExecutor<T, E> executor, WxMpApiUrl url, E data) throws WxErrorException;

  /**
   * 设置当微信系统响应系统繁忙时，要等待多少 retrySleepMillis(ms) * 2^(重试次数 - 1) 再发起重试.
   *
-   * @param retrySleepMillis 默认：1000ms
+   * @param retrySleepMillis 重试等待时间，单位毫秒，默认1000ms
   */
  void setRetrySleepMillis(int retrySleepMillis);

@@ -337,36 +338,36 @@ public interface WxMpService extends WxService {
   * 默认：5次
   * </pre>
   *
-   * @param maxRetryTimes 最大重试次数
+   * @param maxRetryTimes 最大重试次数，默认5次
   */
  void setMaxRetryTimes(int maxRetryTimes);

  /**
   * 获取WxMpConfigStorage 对象.
   *
-   * @return WxMpConfigStorage wx mp config storage
+   * @return WxMpConfigStorage 微信公众号配置存储对象
   */
  WxMpConfigStorage getWxMpConfigStorage();

  /**
   * 设置 {@link WxMpConfigStorage} 的实现. 兼容老版本
   *
-   * @param wxConfigProvider .
+   * @param wxConfigProvider 微信公众号配置存储对象
   */
  void setWxMpConfigStorage(WxMpConfigStorage wxConfigProvider);

  /**
   * Map里 加入新的 {@link WxMpConfigStorage}，适用于动态添加新的微信公众号配置.
   *
-   * @param mpId          公众号id
-   * @param configStorage 新的微信配置
+   * @param mpId          公众号id，用于标识不同的公众号
+   * @param configStorage 新的微信配置，微信公众号配置存储对象
   */
  void addConfigStorage(String mpId, WxMpConfigStorage configStorage);

  /**
   * 从 Map中 移除 {@link String mpId} 所对应的 {@link WxMpConfigStorage}，适用于动态移除微信公众号配置.
   *
-   * @param mpId 对应公众号的标识
+   * @param mpId 对应公众号的标识，用于标识不同的公众号
   */
  void removeConfigStorage(String mpId);

@@ -374,14 +375,14 @@ public interface WxMpService extends WxService {
   * 注入多个 {@link WxMpConfigStorage} 的实现. 并为每个 {@link WxMpConfigStorage} 赋予不同的 {@link String mpId} 值
   * 随机采用一个{@link String mpId}进行Http初始化操作
   *
-   * @param configStorages WxMpConfigStorage map
+   * @param configStorages WxMpConfigStorage map，公众号id到配置存储对象的映射
   */
  void setMultiConfigStorages(Map<String, WxMpConfigStorage> configStorages);

  /**
   * 注入多个 {@link WxMpConfigStorage} 的实现. 并为每个 {@link WxMpConfigStorage} 赋予不同的 {@link String label} 值
   *
-   * @param configStorages WxMpConfigStorage map
+   * @param configStorages WxMpConfigStorage map，公众号id到配置存储对象的映射
   * @param defaultMpId    设置一个{@link WxMpConfigStorage} 所对应的{@link String mpId}进行Http初始化
   */
  void setMultiConfigStorages(Map<String, WxMpConfigStorage> configStorages, String defaultMpId);
@@ -389,132 +390,146 @@ public interface WxMpService extends WxService {
  /**
   * 进行相应的公众号切换.
   *
-   * @param mpId 公众号标识
-   * @return 切换是否成功 boolean
+   * @param mpId 公众号标识，用于标识不同的公众号
+   * @return 切换是否成功，true表示成功，false表示失败
   */
  boolean switchover(String mpId);

+  /**
+   * 进行相应的公众号切换，支持自定义配置获取函数.
+   *
+   * @param mpId 公众号标识，用于标识不同的公众号
+   * @param func 自定义配置获取函数，当配置不存在时使用
+   * @return 切换是否成功，true表示成功，false表示失败
+   */
  boolean switchover(String mpId, Function<String, WxMpConfigStorage> func);

  /**
   * 进行相应的公众号切换.
   *
-   * @param mpId 公众号标识
+   * @param mpId 公众号标识，用于标识不同的公众号
   * @return 切换成功 ，则返回当前对象，方便链式调用，否则抛出异常
   */
  WxMpService switchoverTo(String mpId);

+  /**
+   * 进行相应的公众号切换，支持自定义配置获取函数.
+   *
+   * @param mpId 公众号标识，用于标识不同的公众号
+   * @param func 自定义配置获取函数，当配置不存在时使用
+   * @return 切换成功 ，则返回当前对象，方便链式调用，否则抛出异常
+   */
  WxMpService switchoverTo(String mpId, Function<String, WxMpConfigStorage> func);

  /**
   * 返回客服接口方法实现类，以方便调用其各个接口.
   *
-   * @return WxMpKefuService kefu service
+   * @return WxMpKefuService 客服服务接口
   */
  WxMpKefuService getKefuService();

  /**
   * 返回素材相关接口方法的实现类对象，以方便调用其各个接口.
   *
-   * @return WxMpMaterialService material service
+   * @return WxMpMaterialService 素材服务接口
   */
  WxMpMaterialService getMaterialService();

  /**
   * 返回菜单相关接口方法的实现类对象，以方便调用其各个接口.
   *
-   * @return WxMpMenuService menu service
+   * @return WxMpMenuService 菜单服务接口
   */
  WxMpMenuService getMenuService();

  /**
   * 返回用户相关接口方法的实现类对象，以方便调用其各个接口.
   *
-   * @return WxMpUserService user service
+   * @return WxMpUserService 用户服务接口
   */
  WxMpUserService getUserService();

  /**
   * 返回用户标签相关接口方法的实现类对象，以方便调用其各个接口.
   *
-   * @return WxMpUserTagService user tag service
+   * @return WxMpUserTagService 用户标签服务接口
   */
  WxMpUserTagService getUserTagService();

  /**
   * 返回二维码相关接口方法的实现类对象，以方便调用其各个接口.
   *
-   * @return WxMpQrcodeService qrcode service
+   * @return WxMpQrcodeService 二维码服务接口
   */
  WxMpQrcodeService getQrcodeService();

  /**
   * 返回卡券相关接口方法的实现类对象，以方便调用其各个接口.
   *
-   * @return WxMpCardService card service
+   * @return WxMpCardService 卡券服务接口
   */
  WxMpCardService getCardService();

  /**
   * 返回数据分析统计相关接口方法的实现类对象，以方便调用其各个接口.
   *
-   * @return WxMpDataCubeService data cube service
+   * @return WxMpDataCubeService 数据分析服务接口
   */
  WxMpDataCubeService getDataCubeService();

  /**
   * 返回用户黑名单管理相关接口方法的实现类对象，以方便调用其各个接口.
   *
-   * @return WxMpUserBlacklistService black list service
+   * @return WxMpUserBlacklistService 用户黑名单服务接口
   */
  WxMpUserBlacklistService getBlackListService();

  /**
   * 返回门店管理相关接口方法的实现类对象，以方便调用其各个接口.
   *
-   * @return WxMpStoreService store service
+   * @return WxMpStoreService 门店服务接口
   */
  WxMpStoreService getStoreService();

  /**
   * 返回模板消息相关接口方法的实现类对象，以方便调用其各个接口.
   *
-   * @return WxMpTemplateMsgService template msg service
+   * @return WxMpTemplateMsgService 模板消息服务接口
   */
  WxMpTemplateMsgService getTemplateMsgService();

  /**
   * 返回一次性订阅消息相关接口方法的实现类对象，以方便调用其各个接口.
   *
-   * @return WxMpSubscribeMsgService subscribe msg service
+   * @return WxMpSubscribeMsgService 订阅消息服务接口
   */
  WxMpSubscribeMsgService getSubscribeMsgService();

  /**
   * 返回硬件平台相关接口方法的实现类对象，以方便调用其各个接口.
   *
-   * @return WxMpDeviceService device service
+   * @return WxMpDeviceService 硬件平台服务接口
   */
  WxMpDeviceService getDeviceService();

  /**
   * 返回摇一摇周边相关接口方法的实现类对象，以方便调用其各个接口.
   *
-   * @return WxMpShakeService shake service
+   * @return WxMpShakeService 摇一摇周边服务接口
   */
  WxMpShakeService getShakeService();

  /**
   * 返回会员卡相关接口方法的实现类对象，以方便调用其各个接口.
   *
-   * @return WxMpMemberCardService member card service
+   * @return WxMpMemberCardService 会员卡服务接口
   */
  WxMpMemberCardService getMemberCardService();

  /**
   * 返回营销相关接口方法的实现类对象，以方便调用其各个接口.
   *
-   * @return WxMpMarketingService marketing service
+   * @return WxMpMarketingService 营销服务接口
   */
  WxMpMarketingService getMarketingService();

@@ -526,329 +541,329 @@ public interface WxMpService extends WxService {
  /**
   * 获取RequestHttp对象.
   *
-   * @return RequestHttp对象 request http
+   * @return RequestHttp对象 HTTP请求处理对象
   */
  RequestHttp<?, ?> getRequestHttp();

  /**
   * 返回群发消息相关接口方法的实现类对象，以方便调用其各个接口.
   *
-   * @return WxMpMassMessageService mass message service
+   * @return WxMpMassMessageService 群发消息服务接口
   */
  WxMpMassMessageService getMassMessageService();

  /**
   * 返回AI开放接口方法的实现类对象，以方便调用其各个接口.
   *
-   * @return WxMpAiOpenService ai open service
+   * @return WxMpAiOpenService AI开放服务接口
   */
  WxMpAiOpenService getAiOpenService();

  /**
   * 返回WIFI接口方法的实现类对象，以方便调用其各个接口.
   *
-   * @return WxMpWifiService wifi service
+   * @return WxMpWifiService WIFI服务接口
   */
  WxMpWifiService getWifiService();

  /**
-   * 返回WIFI接口方法的实现类对象，以方便调用其各个接口.
+   * 返回OCR接口方法的实现类对象，以方便调用其各个接口.
   *
-   * @return WxMpWifiService ocr service
+   * @return WxOcrService OCR服务接口
   */
  WxOcrService getOcrService();

  /**
   * 返回图像处理接口的实现类对象，以方便调用其各个接口.
   *
-   * @return WxImgProcService img proc service
+   * @return WxImgProcService 图像处理服务接口
   */
  WxImgProcService getImgProcService();

  /**
   * 返回电子发票报销方相关接口
   *
-   * @return WxMpReimburseInvoiceService reimburse invoice service
+   * @return WxMpReimburseInvoiceService 电子发票报销方服务接口
   */
  WxMpReimburseInvoiceService getReimburseInvoiceService();

  /**
   * 返回草稿箱相关接口
   *
-   * @return WxMpDraftService draft service
+   * @return WxMpDraftService 草稿箱服务接口
   */
  WxMpDraftService getDraftService();

  /**
   * 返回发布能力接口
   *
-   * @return WxMpFreePublishService free publish service
+   * @return WxMpFreePublishService 发布能力服务接口
   */
  WxMpFreePublishService getFreePublishService();

  /**
-   * .
+   * 设置电子发票报销方服务接口
   *
-   * @param reimburseInvoiceService .
+   * @param reimburseInvoiceService 电子发票报销方服务接口
   */
  void setReimburseInvoiceService(WxMpReimburseInvoiceService reimburseInvoiceService);

  /**
-   * .
+   * 设置客服服务接口
   *
-   * @param kefuService .
+   * @param kefuService 客服服务接口
   */
  void setKefuService(WxMpKefuService kefuService);

  /**
-   * .
+   * 设置素材服务接口
   *
-   * @param materialService .
+   * @param materialService 素材服务接口
   */
  void setMaterialService(WxMpMaterialService materialService);

  /**
-   * .
+   * 设置菜单服务接口
   *
-   * @param menuService .
+   * @param menuService 菜单服务接口
   */
  void setMenuService(WxMpMenuService menuService);

  /**
-   * .
+   * 设置用户服务接口
   *
-   * @param userService .
+   * @param userService 用户服务接口
   */
  void setUserService(WxMpUserService userService);

  /**
-   * .
+   * 设置用户标签服务接口
   *
-   * @param userTagService .
+   * @param userTagService 用户标签服务接口
   */
  void setUserTagService(WxMpUserTagService userTagService);

  /**
-   * .
+   * 设置二维码服务接口
   *
-   * @param qrcodeService .
+   * @param qrcodeService 二维码服务接口
   */
  void setQrcodeService(WxMpQrcodeService qrcodeService);

  /**
-   * .
+   * 设置卡券服务接口
   *
-   * @param cardService .
+   * @param cardService 卡券服务接口
   */
  void setCardService(WxMpCardService cardService);

  /**
-   * .
+   * 设置门店服务接口
   *
-   * @param storeService .
+   * @param storeService 门店服务接口
   */
  void setStoreService(WxMpStoreService storeService);

  /**
-   * .
+   * 设置数据分析服务接口
   *
-   * @param dataCubeService .
+   * @param dataCubeService 数据分析服务接口
   */
  void setDataCubeService(WxMpDataCubeService dataCubeService);

  /**
-   * .
+   * 设置用户黑名单服务接口
   *
-   * @param blackListService .
+   * @param blackListService 用户黑名单服务接口
   */
  void setBlackListService(WxMpUserBlacklistService blackListService);

  /**
-   * .
+   * 设置模板消息服务接口
   *
-   * @param templateMsgService .
+   * @param templateMsgService 模板消息服务接口
   */
  void setTemplateMsgService(WxMpTemplateMsgService templateMsgService);

  /**
-   * .
+   * 设置硬件平台服务接口
   *
-   * @param deviceService .
+   * @param deviceService 硬件平台服务接口
   */
  void setDeviceService(WxMpDeviceService deviceService);

  /**
-   * .
+   * 设置摇一摇周边服务接口
   *
-   * @param shakeService .
+   * @param shakeService 摇一摇周边服务接口
   */
  void setShakeService(WxMpShakeService shakeService);

  /**
-   * .
+   * 设置会员卡服务接口
   *
-   * @param memberCardService .
+   * @param memberCardService 会员卡服务接口
   */
  void setMemberCardService(WxMpMemberCardService memberCardService);

  /**
-   * .
+   * 设置群发消息服务接口
   *
-   * @param massMessageService .
+   * @param massMessageService 群发消息服务接口
   */
  void setMassMessageService(WxMpMassMessageService massMessageService);

  /**
-   * .
+   * 设置AI开放服务接口
   *
-   * @param aiOpenService .
+   * @param aiOpenService AI开放服务接口
   */
  void setAiOpenService(WxMpAiOpenService aiOpenService);

  /**
-   * .
+   * 设置营销服务接口
   *
-   * @param marketingService .
+   * @param marketingService 营销服务接口
   */
  void setMarketingService(WxMpMarketingService marketingService);

  /**
-   * .
+   * 设置OCR服务接口
   *
-   * @param ocrService .
+   * @param ocrService OCR服务接口
   */
  void setOcrService(WxOcrService ocrService);

  /**
-   * .
+   * 设置图像处理服务接口
   *
-   * @param imgProcService .
+   * @param imgProcService 图像处理服务接口
   */
  void setImgProcService(WxImgProcService imgProcService);

  /**
   * 返回评论数据管理接口方法的实现类对象，以方便调用其各个接口.
   *
-   * @return WxMpWifiService comment service
+   * @return WxMpCommentService 评论数据管理服务接口
   */
  WxMpCommentService getCommentService();

  /**
-   * .
+   * 设置评论数据管理服务接口
   *
-   * @param commentService .
+   * @param commentService 评论数据管理服务接口
   */
  void setCommentService(WxMpCommentService commentService);

  /**
-   * Gets oauth2 service.
+   * 获取OAuth2服务接口
   *
-   * @return the oauth2 service
+   * @return WxOAuth2Service OAuth2服务接口
   */
  WxOAuth2Service getOAuth2Service();

  /**
-   * Sets oauth2Service.
+   * 设置OAuth2服务接口
   *
-   * @param oAuth2Service the o auth 2 service
+   * @param oAuth2Service OAuth2服务接口
   */
  void setOAuth2Service(WxOAuth2Service oAuth2Service);

  /**
-   * Gets guide service.
+   * 获取微信导购服务接口
   *
-   * @return the guide service
+   * @return WxMpGuideService 微信导购服务接口
   */
  WxMpGuideService getGuideService();

  /**
-   * Sets guide service.
+   * 设置微信导购服务接口
   *
-   * @param guideService the guide service
+   * @param guideService 微信导购服务接口
   */
  void setGuideService(WxMpGuideService guideService);

  /**
-   * Gets guideBuyer service.
+   * 获取微信导购买家服务接口
   *
-   * @return the guideBuyer service
+   * @return WxMpGuideBuyerService 微信导购买家服务接口
   */
  WxMpGuideBuyerService getGuideBuyerService();

  /**
-   * Sets guideBuyer service.
+   * 设置微信导购买家服务接口
   *
-   * @param guideBuyerService the guideBuyer service
+   * @param guideBuyerService 微信导购买家服务接口
   */
  void setGuideBuyerService(WxMpGuideBuyerService guideBuyerService);

  /**
-   * Gets guideTag service.
+   * 获取微信导购标签服务接口
   *
-   * @return the guide service
+   * @return WxMpGuideTagService 微信导购标签服务接口
   */
  WxMpGuideTagService getGuideTagService();

  /**
-   * Sets guideTag service.
+   * 设置微信导购标签服务接口
   *
-   * @param guideTagService the guideTag service
+   * @param guideTagService 微信导购标签服务接口
   */
  void setGuideTagService(WxMpGuideTagService guideTagService);

  /**
-   * Gets guideMaterial service.
+   * 获取微信导购素材服务接口
   *
-   * @return the guideMaterial service
+   * @return WxMpGuideMaterialService 微信导购素材服务接口
   */
  WxMpGuideMaterialService getGuideMaterialService();

  /**
-   * Sets guideMaterial service.
+   * 设置微信导购素材服务接口
   *
-   * @param guideMaterialService the guideMaterial service
+   * @param guideMaterialService 微信导购素材服务接口
   */
  void setGuideMaterialService(WxMpGuideMaterialService guideMaterialService);

  /**
-   * Gets guideMassedJob service.
+   * 获取微信导购批量任务服务接口
   *
-   * @return the guideMassedJob service
+   * @return WxMpGuideMassedJobService 微信导购批量任务服务接口
   */
  WxMpGuideMassedJobService getGuideMassedJobService();

  /**
-   * Sets guide service.
+   * 设置微信导购批量任务服务接口
   *
-   * @param guideMassedJobService the guide service
+   * @param guideMassedJobService 微信导购批量任务服务接口
   */
  void setGuideMassedJobService(WxMpGuideMassedJobService guideMassedJobService);

  /**
-   * Gets merchant invoice service.
+   * 获取微信商户发票服务接口
   *
-   * @return the merchant invoice service
+   * @return WxMpMerchantInvoiceService 微信商户发票服务接口
   */
  WxMpMerchantInvoiceService getMerchantInvoiceService();

  /**
-   * Sets merchant invoice service.
+   * 设置微信商户发票服务接口
   *
-   * @param merchantInvoiceService the merchant invoice service
+   * @param merchantInvoiceService 微信商户发票服务接口
   */
  void setMerchantInvoiceService(WxMpMerchantInvoiceService merchantInvoiceService);

  /**
-   * Sets draft service.
+   * 设置草稿箱服务接口
   *
-   * @param draftService the draft service
+   * @param draftService 草稿箱服务接口
   */
  void setDraftService(WxMpDraftService draftService);

  /**
-   * Sets free publish service.
+   * 设置发布能力服务接口
   *
-   * @param freePublishService the free publish service
+   * @param freePublishService 发布能力服务接口
   */
  void setFreePublishService(WxMpFreePublishService freePublishService);
 }
--- a/weixin-java-mp/src/main/java/me/chanjar/weixin/mp/api/WxMpTemplateMsgService.java
+++ b/weixin-java-mp/src/main/java/me/chanjar/weixin/mp/api/WxMpTemplateMsgService.java
@@ -8,105 +8,178 @@ import me.chanjar.weixin.mp.bean.template.WxMpTemplateMessage;
 import java.util.List;

 /**
- * <pre>
 * 模板消息接口
- * http://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1433751277&token=&lang=zh_CN
+ * <p>
+ * 提供微信模板消息的发送、行业设置、模板管理等功能。
+ * 模板消息用于在用户触发特定事件后，向用户发送重要的服务通知。
+ * </p>
+ * <p>
+ * 详情请见：<a href="http://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1433751277">模板消息开发文档</a>
+ * </p>
 * Created by Binary Wang on 2016-10-14.
+ *
 * @author miller.lin
- * @author  <a href="https://github.com/binarywang">Binary Wang</a> </pre>
+ * @author <a href="https://github.com/binarywang">Binary Wang</a>
 */
 public interface WxMpTemplateMsgService {
-  /**
-   * <pre>
-   * 设置所属行业
-   * 官方文档中暂未告知响应内容
-   * 详情请见：http://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1433751277&token=&lang=zh_CN
-   * </pre>
-   *
-   * @param wxMpIndustry 行业信息
-   * @return 是否成功 industry
-   * @throws WxErrorException .
-   */
-  boolean setIndustry(WxMpTemplateIndustry wxMpIndustry) throws WxErrorException;
+    /**
+     * <pre>
+     * 设置所属行业
+     * 官方文档中暂未告知响应内容
+     * </pre>
+     *
+     * @param wxMpIndustry 行业信息
+     * @return 是否成功设置行业
+     * @throws WxErrorException 微信API调用异常，可能包括：
+     *                          <ul>
+     *                            <li>40001 - 获取access_token时AppSecret错误，或者access_token无效</li>
+     *                            <li>40002 - 请确保grant_type字段值为client_credential</li>
+     *                            <li>40003 - appid对应公众号请开发者使用绑定的公众号测试</li>
+     *                            <li>40004 - appid不正确</li>
+     *                            <li>40006 - access_token超时</li>
+     *                            <li>48001 - api功能未授权</li>
+     *                            <li>45009 - 调用接口的QPS超限</li>
+     *                            <li>其他业务错误码</li>
+     *                          </ul>
+     * @see <a href="http://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1433751277">设置所属行业</a>
+     */
+    boolean setIndustry(WxMpTemplateIndustry wxMpIndustry) throws WxErrorException;

-  /***
-   * <pre>
-   * 获取设置的行业信息
-   * 详情请见：http://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1433751277&token=&lang=zh_CN
-   * </pre>
-   *
-   * @return wxMpIndustry industry
-   * @throws WxErrorException .
-   */
-  WxMpTemplateIndustry getIndustry() throws WxErrorException;
+    /**
+     * <pre>
+     * 获取设置的行业信息
+     * </pre>
+     *
+     * @return 行业信息对象
+     * @throws WxErrorException 微信API调用异常，可能包括：
+     *                          <ul>
+     *                            <li>40001 - 获取access_token时AppSecret错误，或者access_token无效</li>
+     *                            <li>40002 - 请确保grant_type字段值为client_credential</li>
+     *                            <li>40003 - appid对应公众号请开发者使用绑定的公众号测试</li>
+     *                            <li>40004 - appid不正确</li>
+     *                            <li>40006 - access_token超时</li>
+     *                            <li>48001 - api功能未授权</li>
+     *                            <li>45009 - 调用接口的QPS超限</li>
+     *                            <li>其他业务错误码</li>
+     *                          </ul>
+     * @see <a href="http://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1433751277">获取设置的行业信息</a>
+     */
+    WxMpTemplateIndustry getIndustry() throws WxErrorException;

-  /**
-   * <pre>
-   * 发送模板消息
-   * 详情请见: http://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1433751277&token=&lang=zh_CN
-   * </pre>
-   *
-   * @param templateMessage 模板消息
-   * @return 消息Id string
-   * @throws WxErrorException .
-   */
-  String sendTemplateMsg(WxMpTemplateMessage templateMessage) throws WxErrorException;
+    /**
+     * <pre>
+     * 发送模板消息
+     * </pre>
+     *
+     * @param templateMessage 模板消息对象
+     * @return 消息ID，可用于查询模板消息发送状态
+     * @throws WxErrorException 微信API调用异常，可能包括：
+     *                          <ul>
+     *                            <li>40001 - 获取access_token时AppSecret错误，或者access_token无效</li>
+     *                            <li>40002 - 请确保grant_type字段值为client_credential</li>
+     *                            <li>40003 - appid对应公众号请开发者使用绑定的公众号测试</li>
+     *                            <li>40004 - appid不正确</li>
+     *                            <li>40006 - access_token超时</li>
+     *                            <li>48001 - api功能未授权</li>
+     *                            <li>45009 - 调用接口的QPS超限</li>
+     *                            <li>其他业务错误码</li>
+     *                          </ul>
+     * @see <a href="http://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1433751277">发送模板消息</a>
+     */
+    String sendTemplateMsg(WxMpTemplateMessage templateMessage) throws WxErrorException;

-  /**
-   * <pre>
-   * 获得模板ID
-   * 从行业模板库选择模板到账号后台，获得模板ID的过程可在MP中完成
-   * 详情请见: http://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1433751277&token=&lang=zh_CN
-   * 接口地址格式：https://api.weixin.qq.com/cgi-bin/template/api_add_template?access_token=ACCESS_TOKEN
-   * </pre>
-   *
-   * @param shortTemplateId 模板库中模板的编号，有“TM**”和“OPENTMTM**”等形式
-   * @return templateId 模板Id
-   * @throws WxErrorException .
-   * @deprecated 请使用 addTemplate(java.lang.String, java.util.List)
-   */
-  @Deprecated
-  String addTemplate(String shortTemplateId) throws WxErrorException;
+    /**
+     * <pre>
+     * 获得模板ID
+     * 从行业模板库选择模板到账号后台，获得模板ID的过程可在MP中完成
+     * </pre>
+     *
+     * @param shortTemplateId 模板库中模板的编号，有"TM**"和"OPENTMTM**"等形式
+     * @return 模板ID
+     * @throws WxErrorException 微信API调用异常，可能包括：
+     *                          <ul>
+     *                            <li>40001 - 获取access_token时AppSecret错误，或者access_token无效</li>
+     *                            <li>40002 - 请确保grant_type字段值为client_credential</li>
+     *                            <li>40003 - appid对应公众号请开发者使用绑定的公众号测试</li>
+     *                            <li>40004 - appid不正确</li>
+     *                            <li>40006 - access_token超时</li>
+     *                            <li>48001 - api功能未授权</li>
+     *                            <li>45009 - 调用接口的QPS超限</li>
+     *                            <li>其他业务错误码</li>
+     *                          </ul>
+     * @deprecated 请使用 {@link #addTemplate(String, List)}
+     * @see <a href="http://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1433751277">获得模板ID</a>
+     */
+    @Deprecated
+    String addTemplate(String shortTemplateId) throws WxErrorException;

-  /**
-   * <pre>
-   * 获得模板ID
-   * 从类目模板库选择模板到账号后台，获得模板ID的过程可在MP中完成
-   * 详情请见: http://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1433751277&token=&lang=zh_CN
-   * 接口地址格式：https://api.weixin.qq.com/cgi-bin/template/api_add_template?access_token=ACCESS_TOKEN
-   * </pre>
-   *
-   * @param shortTemplateId 模板库中模板的编号，有“TM**”和“OPENTMTM**”等形式,对于类目模板，为纯数字ID
-   * @param keywordNameList 选用的类目模板的关键词,按顺序传入,如果为空，或者关键词不在模板库中，会返回40246错误码
-   * @return templateId 模板Id
-   * @throws WxErrorException .
-   */
-  String addTemplate(String shortTemplateId, List<String> keywordNameList) throws WxErrorException;
+    /**
+     * <pre>
+     * 获得模板ID
+     * 从类目模板库选择模板到账号后台，获得模板ID的过程可在MP中完成
+     * </pre>
+     *
+     * @param shortTemplateId  模板库中模板的编号，有"TM**"和"OPENTMTM**"等形式，对于类目模板，为纯数字ID
+     * @param keywordNameList 选用的类目模板的关键词，按顺序传入，如果为空，或者关键词不在模板库中，会返回40246错误码
+     * @return 模板ID
+     * @throws WxErrorException 微信API调用异常，可能包括：
+     *                          <ul>
+     *                            <li>40001 - 获取access_token时AppSecret错误，或者access_token无效</li>
+     *                            <li>40002 - 请确保grant_type字段值为client_credential</li>
+     *                            <li>40003 - appid对应公众号请开发者使用绑定的公众号测试</li>
+     *                            <li>40004 - appid不正确</li>
+     *                            <li>40006 - access_token超时</li>
+     *                            <li>48001 - api功能未授权</li>
+     *                            <li>45009 - 调用接口的QPS超限</li>
+     *                            <li>40246 - 关键词不在模板库中</li>
+     *                            <li>其他业务错误码</li>
+     *                          </ul>
+     * @see <a href="http://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1433751277">获得模板ID</a>
+     */
+    String addTemplate(String shortTemplateId, List<String> keywordNameList) throws WxErrorException;

-  /**
-   * <pre>
-   * 获取模板列表
-   * 获取已添加至账号下所有模板列表，可在MP中查看模板列表信息，为方便第三方开发者，提供通过接口调用的方式来获取账号下所有模板信息
-   * 详情请见: http://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1433751277&token=&lang=zh_CN
-   * 接口地址格式：https://api.weixin.qq.com/cgi-bin/template/get_all_private_template?access_token=ACCESS_TOKEN
-   * </pre>
-   *
-   * @return templateId 模板Id
-   * @throws WxErrorException .
-   */
-  List<WxMpTemplate> getAllPrivateTemplate() throws WxErrorException;
+    /**
+     * <pre>
+     * 获取模板列表
+     * 获取已添加至账号下所有模板列表，可在MP中查看模板列表信息，为方便第三方开发者，提供通过接口调用的方式来获取账号下所有模板信息
+     * </pre>
+     *
+     * @return 模板列表，包含所有已添加的模板信息
+     * @throws WxErrorException 微信API调用异常，可能包括：
+     *                          <ul>
+     *                            <li>40001 - 获取access_token时AppSecret错误，或者access_token无效</li>
+     *                            <li>40002 - 请确保grant_type字段值为client_credential</li>
+     *                            <li>40003 - appid对应公众号请开发者使用绑定的公众号测试</li>
+     *                            <li>40004 - appid不正确</li>
+     *                            <li>40006 - access_token超时</li>
+     *                            <li>48001 - api功能未授权</li>
+     *                            <li>45009 - 调用接口的QPS超限</li>
+     *                            <li>其他业务错误码</li>
+     *                          </ul>
+     * @see <a href="http://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1433751277">获取模板列表</a>
+     */
+    List<WxMpTemplate> getAllPrivateTemplate() throws WxErrorException;

-  /**
-   * <pre>
-   * 删除模板
-   * 删除模板可在MP中完成，为方便第三方开发者，提供通过接口调用的方式来删除某账号下的模板
-   * 详情请见: http://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1433751277&token=&lang=zh_CN
-   * 接口地址格式：https://api.weixin.qq.com/cgi-bin/template/del_private_template?access_token=ACCESS_TOKEN
-   * </pre>
-   *
-   * @param templateId 模板Id
-   * @return . boolean
-   * @throws WxErrorException .
-   */
-  boolean delPrivateTemplate(String templateId) throws WxErrorException;
+    /**
+     * <pre>
+     * 删除模板
+     * 删除模板可在MP中完成，为方便第三方开发者，提供通过接口调用的方式来删除某账号下的模板
+     * </pre>
+     *
+     * @param templateId 模板ID
+     * @return 是否成功删除
+     * @throws WxErrorException 微信API调用异常，可能包括：
+     *                          <ul>
+     *                            <li>40001 - 获取access_token时AppSecret错误，或者access_token无效</li>
+     *                            <li>40002 - 请确保grant_type字段值为client_credential</li>
+     *                            <li>40003 - appid对应公众号请开发者使用绑定的公众号测试</li>
+     *                            <li>40004 - appid不正确</li>
+     *                            <li>40006 - access_token超时</li>
+     *                            <li>48001 - api功能未授权</li>
+     *                            <li>45009 - 调用接口的QPS超限</li>
+     *                            <li>其他业务错误码</li>
+     *                          </ul>
+     * @see <a href="http://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1433751277">删除模板</a>
+     */
+    boolean delPrivateTemplate(String templateId) throws WxErrorException;
 }
--- a/weixin-java-mp/src/main/java/me/chanjar/weixin/mp/api/WxMpUserService.java
+++ b/weixin-java-mp/src/main/java/me/chanjar/weixin/mp/api/WxMpUserService.java
@@ -22,9 +22,9 @@ public interface WxMpUserService {
     * 接口地址：https://api.weixin.qq.com/cgi-bin/user/info/updateremark?access_token=ACCESS_TOKEN
     * </pre>
     *
-     * @param openid 用户openid
-     * @param remark 备注名
-     * @throws WxErrorException the wx error exception
+     * @param openid 用户openid，标识具体的用户
+     * @param remark 备注名，长度限制为30字符以内
+     * @throws WxErrorException 微信API调用异常
     */
    void userUpdateRemark(String openid, String remark) throws WxErrorException;

@@ -36,9 +36,9 @@ public interface WxMpUserService {
     * 接口地址：https://api.weixin.qq.com/cgi-bin/user/info?access_token=ACCESS_TOKEN&openid=OPENID&lang=zh_CN
     * </pre>
     *
-     * @param openid 用户openid
-     * @return the wx mp user
-     * @throws WxErrorException the wx error exception
+     * @param openid 用户openid，标识具体的用户
+     * @return 用户基本信息，包含昵称、头像、性别、关注时间等
+     * @throws WxErrorException 微信API调用异常
     */
    WxMpUser userInfo(String openid) throws WxErrorException;

@@ -50,10 +50,10 @@ public interface WxMpUserService {
     * 接口地址：https://api.weixin.qq.com/cgi-bin/user/info?access_token=ACCESS_TOKEN&openid=OPENID&lang=zh_CN
     * </pre>
     *
-     * @param openid 用户openid
+     * @param openid 用户openid，标识具体的用户
     * @param lang   语言，zh_CN 简体(默认)，zh_TW 繁体，en 英语
-     * @return the wx mp user
-     * @throws WxErrorException the wx error exception
+     * @return 用户基本信息，包含昵称、头像、性别、关注时间等
+     * @throws WxErrorException 微信API调用异常
     */
    WxMpUser userInfo(String openid, String lang) throws WxErrorException;

@@ -66,9 +66,9 @@ public interface WxMpUserService {
     * 接口地址：https://api.weixin.qq.com/cgi-bin/user/info/batchget?access_token=ACCESS_TOKEN
     * </pre>
     *
-     * @param openidList 用户openid列表
-     * @return the list
-     * @throws WxErrorException the wx error exception
+     * @param openidList 用户openid列表，最多100个
+     * @return 用户基本信息列表，包含每个用户的基本信息
+     * @throws WxErrorException 微信API调用异常
     */
    List<WxMpUser> userInfoList(List<String> openidList) throws WxErrorException;

@@ -81,9 +81,9 @@ public interface WxMpUserService {
     * 接口地址：https://api.weixin.qq.com/cgi-bin/user/info/batchget?access_token=ACCESS_TOKEN
     * </pre>
     *
-     * @param userQuery 详细查询参数
-     * @return the list
-     * @throws WxErrorException the wx error exception
+     * @param userQuery 详细查询参数，包含openid列表和语言设置
+     * @return 用户基本信息列表，包含每个用户的基本信息
+     * @throws WxErrorException 微信API调用异常
     */
    List<WxMpUser> userInfoList(WxMpUserQuery userQuery) throws WxErrorException;

@@ -99,8 +99,8 @@ public interface WxMpUserService {
     * </pre>
     *
     * @param nextOpenid 可选，第一个拉取的OPENID，null为从头开始拉取
-     * @return the wx mp user list
-     * @throws WxErrorException the wx error exception
+     * @return 用户列表，包含关注者OpenID列表和下一个OpenID
+     * @throws WxErrorException 微信API调用异常
     */
    WxMpUserList userList(String nextOpenid) throws WxErrorException;

@@ -109,9 +109,13 @@ public interface WxMpUserService {
     * 获取用户列表（全部）
     * 公众号可通过本接口来获取账号的关注者列表，
     * 关注者列表由一串OpenID（加密后的微信号，每个用户对每个公众号的OpenID是唯一的）组成。
-     * @return the wx mp user list
-     * @throws WxErrorException the wx error exception
-     * @see #userList(java.lang.String) #userList(java.lang.String)的增强，内部进行了多次数据拉取的汇总 详情请见: http://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1421140840&token=&lang=zh_CN http请求方式: GET（请使用https协议） 接口地址：https://api.weixin.qq.com/cgi-bin/user/get?access_token=ACCESS_TOKEN&next_openid=NEXT_OPENID </pre>
+     * @return 用户列表，包含所有关注者的OpenID列表
+     * @throws WxErrorException 微信API调用异常
+     * @see #userList(String) #userList(String)的增强，内部进行了多次数据拉取的汇总
+     * 详情请见: http://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1421140840&token=&lang=zh_CN
+     * http请求方式: GET（请使用https协议）
+     * 接口地址：https://api.weixin.qq.com/cgi-bin/user/get?access_token=ACCESS_TOKEN&next_openid=NEXT_OPENID
+     * </pre>
     */
    WxMpUserList userList() throws WxErrorException;

@@ -126,8 +130,8 @@ public interface WxMpUserService {
     *
     * @param fromAppid  原公众号的 appid
     * @param openidList 需要转换的openid，这些必须是旧账号目前关注的才行，否则会出错；一次最多100个
-     * @return the list
-     * @throws WxErrorException the wx error exception
+     * @return openid转换结果列表，包含原openid和新openid的映射关系
+     * @throws WxErrorException 微信API调用异常
     */
    List<WxMpChangeOpenid> changeOpenid(String fromAppid, List<String> openidList) throws WxErrorException;
 }
--- a/weixin-java-mp/src/main/java/me/chanjar/weixin/mp/api/WxMpUserTagService.java
+++ b/weixin-java-mp/src/main/java/me/chanjar/weixin/mp/api/WxMpUserTagService.java
@@ -8,6 +8,14 @@ import java.util.List;

 /**
 * 用户标签管理相关接口
+ * <p>
+ * 提供微信公众号用户标签的创建、查询、更新、删除等功能。
+ * 通过标签可以方便地对用户进行分组管理和精准营销。
+ * 一个公众号最多可以创建100个标签。
+ * </p>
+ * <p>
+ * 详情请见：<a href="https://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1421140837">用户标签管理</a>
+ * </p>
 * Created by Binary Wang on 2016/9/2.
 *
 * @author <a href="https://github.com/binarywang">Binary Wang</a>
@@ -17,110 +25,193 @@ public interface WxMpUserTagService {
     * <pre>
     * 创建标签
     * 一个公众号，最多可以创建100个标签。
-     * 详情请见：<a href="http://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1421140837&token=&lang=zh_CN">用户标签管理</a>
-     * 接口url格式： https://api.weixin.qq.com/cgi-bin/tags/create?access_token=ACCESS_TOKEN
     * </pre>
     *
     * @param name 标签名字（30个字符以内）
-     * @return the wx user tag
-     * @throws WxErrorException the wx error exception
+     * @return 创建的标签对象，包含标签ID等信息
+     * @throws WxErrorException 微信API调用异常，可能包括：
+     *                          <ul>
+     *                            <li>40001 - 获取access_token时AppSecret错误，或者access_token无效</li>
+     *                            <li>40002 - 请确保grant_type字段值为client_credential</li>
+     *                            <li>40003 - appid对应公众号请开发者使用绑定的公众号测试</li>
+     *                            <li>40004 - appid不正确</li>
+     *                            <li>40006 - access_token超时</li>
+     *                            <li>48001 - api功能未授权</li>
+     *                            <li>45009 - 调用接口的QPS超限</li>
+     *                            <li>其他业务错误码</li>
+     *                          </ul>
+     * @see <a href="https://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1421140837">用户标签管理</a>
+     * @see <a href="https://api.weixin.qq.com/cgi-bin/tags/create">创建标签接口</a>
     */
    WxUserTag tagCreate(String name) throws WxErrorException;

    /**
     * <pre>
     * 获取公众号已创建的标签
-     * 详情请见：<a href="http://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1421140837&token=&lang=zh_CN">用户标签管理</a>
-     * 接口url格式： https://api.weixin.qq.com/cgi-bin/tags/get?access_token=ACCESS_TOKEN
     * </pre>
     *
-     * @return the list
-     * @throws WxErrorException the wx error exception
+     * @return 标签列表，包含所有已创建的标签信息
+     * @throws WxErrorException 微信API调用异常，可能包括：
+     *                          <ul>
+     *                            <li>40001 - 获取access_token时AppSecret错误，或者access_token无效</li>
+     *                            <li>40002 - 请确保grant_type字段值为client_credential</li>
+     *                            <li>40003 - appid对应公众号请开发者使用绑定的公众号测试</li>
+     *                            <li>40004 - appid不正确</li>
+     *                            <li>40006 - access_token超时</li>
+     *                            <li>48001 - api功能未授权</li>
+     *                            <li>45009 - 调用接口的QPS超限</li>
+     *                            <li>其他业务错误码</li>
+     *                          </ul>
+     * @see <a href="https://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1421140837">用户标签管理</a>
+     * @see <a href="https://api.weixin.qq.com/cgi-bin/tags/get">获取标签接口</a>
     */
    List<WxUserTag> tagGet() throws WxErrorException;

    /**
     * <pre>
     * 编辑标签
-     * 详情请见：<a href="http://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1421140837&token=&lang=zh_CN">用户标签管理</a>
-     * 接口url格式： https://api.weixin.qq.com/cgi-bin/tags/update?access_token=ACCESS_TOKEN
+     * 可以修改标签的名称，但不能修改标签ID。
     * </pre>
     *
-     * @param tagId the tag id
-     * @param name  the name
-     * @return the boolean
-     * @throws WxErrorException the wx error exception
+     * @param tagId 标签ID，不能为null
+     * @param name  新的标签名字（30个字符以内）
+     * @return 操作是否成功，true表示成功，false表示失败
+     * @throws WxErrorException 微信API调用异常，可能包括：
+     *                          <ul>
+     *                            <li>40001 - 获取access_token时AppSecret错误，或者access_token无效</li>
+     *                            <li>40002 - 请确保grant_type字段值为client_credential</li>
+     *                            <li>40003 - appid对应公众号请开发者使用绑定的公众号测试</li>
+     *                            <li>40004 - appid不正确</li>
+     *                            <li>40006 - access_token超时</li>
+     *                            <li>48001 - api功能未授权</li>
+     *                            <li>45009 - 调用接口的QPS超限</li>
+     *                            <li>其他业务错误码</li>
+     *                          </ul>
+     * @see <a href="https://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1421140837">用户标签管理</a>
+     * @see <a href="https://api.weixin.qq.com/cgi-bin/tags/update">编辑标签接口</a>
     */
    Boolean tagUpdate(Long tagId, String name) throws WxErrorException;

    /**
     * <pre>
     * 删除标签
-     * 详情请见：<a href="http://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1421140837&token=&lang=zh_CN">用户标签管理</a>
-     * 接口url格式： https://api.weixin.qq.com/cgi-bin/tags/delete?access_token=ACCESS_TOKEN
+     * 删除标签后，该标签下的所有用户将被取消标签。
     * </pre>
     *
-     * @param tagId the tag id
-     * @return the boolean
-     * @throws WxErrorException the wx error exception
+     * @param tagId 标签ID，不能为null
+     * @return 操作是否成功，true表示成功，false表示失败
+     * @throws WxErrorException 微信API调用异常，可能包括：
+     *                          <ul>
+     *                            <li>40001 - 获取access_token时AppSecret错误，或者access_token无效</li>
+     *                            <li>40002 - 请确保grant_type字段值为client_credential</li>
+     *                            <li>40003 - appid对应公众号请开发者使用绑定的公众号测试</li>
+     *                            <li>40004 - appid不正确</li>
+     *                            <li>40006 - access_token超时</li>
+     *                            <li>48001 - api功能未授权</li>
+     *                            <li>45009 - 调用接口的QPS超限</li>
+     *                            <li>其他业务错误码</li>
+     *                          </ul>
+     * @see <a href="https://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1421140837">用户标签管理</a>
+     * @see <a href="https://api.weixin.qq.com/cgi-bin/tags/delete">删除标签接口</a>
     */
    Boolean tagDelete(Long tagId) throws WxErrorException;

    /**
     * <pre>
     * 获取标签下粉丝列表
-     * 详情请见：<a href="http://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1421140837&token=&lang=zh_CN">用户标签管理</a>
-     * 接口url格式： https://api.weixin.qq.com/cgi-bin/user/tag/get?access_token=ACCESS_TOKEN
+     * 可用于获取某个标签下的所有用户信息，支持分页查询。
     * </pre>
     *
-     * @param tagId      the tag id
-     * @param nextOpenid the next openid
-     * @return the wx tag list user
-     * @throws WxErrorException the wx error exception
+     * @param tagId      标签ID，不能为null
+     * @param nextOpenid 第一个拉取用户的openid，不填从头开始拉取
+     * @return 标签下粉丝列表对象，包含用户信息和分页信息
+     * @throws WxErrorException 微信API调用异常，可能包括：
+     *                          <ul>
+     *                            <li>40001 - 获取access_token时AppSecret错误，或者access_token无效</li>
+     *                            <li>40002 - 请确保grant_type字段值为client_credential</li>
+     *                            <li>40003 - appid对应公众号请开发者使用绑定的公众号测试</li>
+     *                            <li>40004 - appid不正确</li>
+     *                            <li>40006 - access_token超时</li>
+     *                            <li>48001 - api功能未授权</li>
+     *                            <li>45009 - 调用接口的QPS超限</li>
+     *                            <li>其他业务错误码</li>
+     *                          </ul>
+     * @see <a href="https://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1421140837">用户标签管理</a>
+     * @see <a href="https://api.weixin.qq.com/cgi-bin/user/tag/get">获取标签下粉丝列表接口</a>
     */
-    WxTagListUser tagListUser(Long tagId, String nextOpenid)
-    throws WxErrorException;
+    WxTagListUser tagListUser(Long tagId, String nextOpenid) throws WxErrorException;

    /**
     * <pre>
     * 批量为用户打标签
-     * 详情请见：<a href="http://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1421140837&token=&lang=zh_CN">用户标签管理</a>
-     * 接口url格式： https://api.weixin.qq.com/cgi-bin/tags/members/batchtagging?access_token=ACCESS_TOKEN
+     * 可以为多个用户同时打上同一个标签。
     * </pre>
     *
-     * @param tagId   the tag id
-     * @param openids the openids
-     * @return the boolean
-     * @throws WxErrorException the wx error exception
+     * @param tagId   标签ID，不能为null
+     * @param openids 用户openid数组，不能为null或空数组
+     * @return 操作是否成功，true表示成功，false表示失败
+     * @throws WxErrorException 微信API调用异常，可能包括：
+     *                          <ul>
+     *                            <li>40001 - 获取access_token时AppSecret错误，或者access_token无效</li>
+     *                            <li>40002 - 请确保grant_type字段值为client_credential</li>
+     *                            <li>40003 - appid对应公众号请开发者使用绑定的公众号测试</li>
+     *                            <li>40004 - appid不正确</li>
+     *                            <li>40006 - access_token超时</li>
+     *                            <li>48001 - api功能未授权</li>
+     *                            <li>45009 - 调用接口的QPS超限</li>
+     *                            <li>其他业务错误码</li>
+     *                          </ul>
+     * @see <a href="https://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1421140837">用户标签管理</a>
+     * @see <a href="https://api.weixin.qq.com/cgi-bin/tags/members/batchtagging">批量为用户打标签接口</a>
     */
    boolean batchTagging(Long tagId, String[] openids) throws WxErrorException;

    /**
     * <pre>
     * 批量为用户取消标签
-     * 详情请见：<a href="http://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1421140837&token=&lang=zh_CN">用户标签管理</a>
-     * 接口url格式： https://api.weixin.qq.com/cgi-bin/tags/members/batchuntagging?access_token=ACCESS_TOKEN
+     * 可以为多个用户同时取消同一个标签。
     * </pre>
     *
-     * @param tagId   the tag id
-     * @param openids the openids
-     * @return the boolean
-     * @throws WxErrorException the wx error exception
+     * @param tagId   标签ID，不能为null
+     * @param openids 用户openid数组，不能为null或空数组
+     * @return 操作是否成功，true表示成功，false表示失败
+     * @throws WxErrorException 微信API调用异常，可能包括：
+     *                          <ul>
+     *                            <li>40001 - 获取access_token时AppSecret错误，或者access_token无效</li>
+     *                            <li>40002 - 请确保grant_type字段值为client_credential</li>
+     *                            <li>40003 - appid对应公众号请开发者使用绑定的公众号测试</li>
+     *                            <li>40004 - appid不正确</li>
+     *                            <li>40006 - access_token超时</li>
+     *                            <li>48001 - api功能未授权</li>
+     *                            <li>45009 - 调用接口的QPS超限</li>
+     *                            <li>其他业务错误码</li>
+     *                          </ul>
+     * @see <a href="https://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1421140837">用户标签管理</a>
+     * @see <a href="https://api.weixin.qq.com/cgi-bin/tags/members/batchuntagging">批量为用户取消标签接口</a>
     */
    boolean batchUntagging(Long tagId, String[] openids) throws WxErrorException;

-
    /**
     * <pre>
     * 获取用户身上的标签列表
-     * 详情请见：<a href="http://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1421140837&token=&lang=zh_CN">用户标签管理</a>
-     * 接口url格式： https://api.weixin.qq.com/cgi-bin/tags/getidlist?access_token=ACCESS_TOKEN
+     * 可查询某个用户被打上的所有标签ID。
     * </pre>
     *
-     * @param openid the openid
-     * @return 标签Id的列表 list
-     * @throws WxErrorException the wx error exception
+     * @param openid 用户的openid，不能为null或空字符串
+     * @return 标签ID的列表，表示该用户被打上的所有标签
+     * @throws WxErrorException 微信API调用异常，可能包括：
+     *                          <ul>
+     *                            <li>40001 - 获取access_token时AppSecret错误，或者access_token无效</li>
+     *                            <li>40002 - 请确保grant_type字段值为client_credential</li>
+     *                            <li>40003 - appid对应公众号请开发者使用绑定的公众号测试</li>
+     *                            <li>40004 - appid不正确</li>
+     *                            <li>40006 - access_token超时</li>
+     *                            <li>48001 - api功能未授权</li>
+     *                            <li>45009 - 调用接口的QPS超限</li>
+     *                            <li>其他业务错误码</li>
+     *                          </ul>
+     * @see <a href="https://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1421140837">用户标签管理</a>
+     * @see <a href="https://api.weixin.qq.com/cgi-bin/tags/getidlist">获取用户身上的标签列表接口</a>
     */
    List<Long> userTagList(String openid) throws WxErrorException;
-
 }
--- a/weixin-java-mp/src/main/java/me/chanjar/weixin/mp/api/impl/WxMpAiOpenServiceImpl.java
+++ b/weixin-java-mp/src/main/java/me/chanjar/weixin/mp/api/impl/WxMpAiOpenServiceImpl.java
@@ -15,59 +15,57 @@ import java.io.File;
 import static me.chanjar.weixin.mp.enums.WxMpApiUrl.AiOpen.*;

 /**
- * <pre>
- *  Created by BinaryWang on 2018/6/9.
- * </pre>
+ * Created by BinaryWang on 2018/6/9.
 *
 * @author <a href="https://github.com/binarywang">Binary Wang</a>
 */
@RequiredArgsConstructor
 public class WxMpAiOpenServiceImpl implements WxMpAiOpenService {
-  private final WxMpService wxMpService;
+    private final WxMpService wxMpService;

-  @Override
-  public void uploadVoice(String voiceId, AiLangType lang, File voiceFile) throws WxErrorException {
-    if (lang == null) {
-      lang = AiLangType.zh_CN;
+    @Override
+    public void uploadVoice(String voiceId, AiLangType lang, File voiceFile) throws WxErrorException {
+        if (lang == null) {
+            lang = AiLangType.zh_CN;
+        }
+
+        this.wxMpService.execute(VoiceUploadRequestExecutor.create(this.wxMpService.getRequestHttp()),
+            String.format(VOICE_UPLOAD_URL.getUrl(this.wxMpService.getWxMpConfigStorage()), "mp3", voiceId, lang.getCode()),
+            voiceFile);
    }

-    this.wxMpService.execute(VoiceUploadRequestExecutor.create(this.wxMpService.getRequestHttp()),
-      String.format(VOICE_UPLOAD_URL.getUrl(this.wxMpService.getWxMpConfigStorage()), "mp3", voiceId, lang.getCode()),
-      voiceFile);
-  }
+    @Override
+    public String queryRecognitionResult(String voiceId, AiLangType lang) throws WxErrorException {
+        if (lang == null) {
+            lang = AiLangType.zh_CN;
+        }

-  @Override
-  public String recogniseVoice(String voiceId, AiLangType lang, File voiceFile) throws WxErrorException {
-    this.uploadVoice(voiceId, lang, voiceFile);
-    return this.queryRecognitionResult(voiceId, lang);
-  }
+        final String response = this.wxMpService.get(VOICE_QUERY_RESULT_URL,
+            String.format("voice_id=%s&lang=%s", voiceId, lang.getCode()));
+        WxError error = WxError.fromJson(response, WxType.MP);
+        if (error.getErrorCode() != 0) {
+            throw new WxErrorException(error);
+        }

-  @Override
-  public String translate(AiLangType langFrom, AiLangType langTo, String content) throws WxErrorException {
-    String response = this.wxMpService.post(String.format(TRANSLATE_URL.getUrl(this.wxMpService.getWxMpConfigStorage()),
-      langFrom.getCode(), langTo.getCode()), content);
-
-    WxError error = WxError.fromJson(response, WxType.MP);
-    if (error.getErrorCode() != 0) {
-      throw new WxErrorException(error);
+        return GsonParser.parse(response).get("result").getAsString();
    }

-    return GsonParser.parse(response).get("to_content").getAsString();
-  }
-
-  @Override
-  public String queryRecognitionResult(String voiceId, AiLangType lang) throws WxErrorException {
-    if (lang == null) {
-      lang = AiLangType.zh_CN;
+    @Override
+    public String recogniseVoice(String voiceId, AiLangType lang, File voiceFile) throws WxErrorException {
+        this.uploadVoice(voiceId, lang, voiceFile);
+        return this.queryRecognitionResult(voiceId, lang);
    }

-    final String response = this.wxMpService.get(VOICE_QUERY_RESULT_URL,
-      String.format("voice_id=%s&lang=%s", voiceId, lang.getCode()));
-    WxError error = WxError.fromJson(response, WxType.MP);
-    if (error.getErrorCode() != 0) {
-      throw new WxErrorException(error);
-    }
+    @Override
+    public String translate(AiLangType langFrom, AiLangType langTo, String content) throws WxErrorException {
+        String response = this.wxMpService.post(String.format(TRANSLATE_URL.getUrl(this.wxMpService.getWxMpConfigStorage()),
+            langFrom.getCode(), langTo.getCode()), content);

-    return GsonParser.parse(response).get("result").getAsString();
-  }
+        WxError error = WxError.fromJson(response, WxType.MP);
+        if (error.getErrorCode() != 0) {
+            throw new WxErrorException(error);
+        }
+
+        return GsonParser.parse(response).get("to_content").getAsString();
+    }
 }
--- a/weixin-java-mp/src/main/java/me/chanjar/weixin/mp/api/impl/WxMpUserTagServiceImpl.java
+++ b/weixin-java-mp/src/main/java/me/chanjar/weixin/mp/api/impl/WxMpUserTagServiceImpl.java
@@ -46,10 +46,10 @@ public class WxMpUserTagServiceImpl implements WxMpUserTagService {
  }

  @Override
-  public Boolean tagUpdate(Long id, String name) throws WxErrorException {
+  public Boolean tagUpdate(Long tagId, String name) throws WxErrorException {
    JsonObject json = new JsonObject();
    JsonObject tagJson = new JsonObject();
-    tagJson.addProperty("id", id);
+    tagJson.addProperty("id", tagId);
    tagJson.addProperty("name", name);
    json.add("tag", tagJson);

@@ -63,10 +63,10 @@ public class WxMpUserTagServiceImpl implements WxMpUserTagService {
  }

  @Override
-  public Boolean tagDelete(Long id) throws WxErrorException {
+  public Boolean tagDelete(Long tagId) throws WxErrorException {
    JsonObject json = new JsonObject();
    JsonObject tagJson = new JsonObject();
-    tagJson.addProperty("id", id);
+    tagJson.addProperty("id", tagId);
    json.add("tag", tagJson);

    String responseContent = this.wxMpService.post(TAGS_DELETE, json.toString());