✨ feat(im): 增加 pinyin 功能

YunaiV
1 parent fc90635a
Showing 5 changed files with 44 additions and 1 deletions
yudao-dependencies/pom.xml
yudao-framework/yudao-common/src/main/java/cn/iocoder/yudao/framework/common/util/string/StrUtils.java
yudao-module-im/pom.xml
yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/controller/admin/friend/ImFriendController.java
yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/controller/admin/friend/vo/ImFriendRespVO.java
@@ -51,6 +51,7 @@
         <anji-plus-captcha.version>1.4.0</anji-plus-captcha.version>
         <jsoup.version>1.21.2</jsoup.version>
         <sensitive-word.version>0.29.5</sensitive-word.version>
+        <pinyin4j.version>2.5.1</pinyin4j.version>
         <lombok.version>1.18.42</lombok.version>
         <mapstruct.version>1.6.3</mapstruct.version>
         <hutool-5.version>5.8.42</hutool-5.version>
@@ -565,6 +566,12 @@
                 <version>${sensitive-word.version}</version>
             </dependency>
+            <dependency>
+                <groupId>com.belerweb</groupId>
+                <artifactId>pinyin4j</artifactId> <!-- 汉字转拼音：作为 hutool PinyinUtil 的底层引擎 -->
+                <version>${pinyin4j.version}</version>
+            </dependency>
+
             <!-- Vert.x -->
             <dependency>
                 <groupId>io.vertx</groupId>
@@ -3,6 +3,7 @@ package cn.iocoder.yudao.framework.common.util.string;
 import cn.hutool.core.text.StrPool;
 import cn.hutool.core.util.ArrayUtil;
 import cn.hutool.core.util.StrUtil;
+import cn.hutool.extra.pinyin.PinyinUtil;
 import org.aspectj.lang.JoinPoint;
 import java.util.Arrays;
@@ -79,6 +80,25 @@ public class StrUtils {
     }
     /**
+     * 转小写拼音，字之间以空格分隔，便于调用方按需拼接 / 取首字母 / 拼音搜索
+     *
+     * 例：「老张」→ "lao zhang"、「ZhangSan」→ "zhangsan"
+     * 英文 / 数字 / 符号原样返回，空值返回 null
+     *
+     * 注意：底层依赖 hutool-extra 的 {@link PinyinUtil}，需要业务模块自行引入拼音引擎依赖
+     * （pinyin4j / TinyPinyin / Bopomofo4j 任选其一），否则运行时会抛 NoClassDefFoundError
+     *
+     * @param str 字符串
+     * @return 拼音串（保留空格分隔）
+     */
+    public static String toPinyin(String str) {
+        if (StrUtil.isBlank(str)) {
+            return null;
+        }
+        return PinyinUtil.getPinyin(str);
+    }
+
+    /**
      * 拼接方法的参数
      *
      * 特殊：排除一些无法序列化的参数，如 ServletRequest、ServletResponse、MultipartFile
@@ -68,6 +68,12 @@
             <artifactId>sensitive-word</artifactId>
         </dependency>
+        <!-- 汉字转拼音：作为 hutool PinyinUtil 的底层引擎，业务侧调用 StrUtils.toPinyin 时按需引入 -->
+        <dependency>
+            <groupId>com.belerweb</groupId>
+            <artifactId>pinyin4j</artifactId>
+        </dependency>
+
         <!-- Test 测试相关 -->
         <dependency>
             <groupId>cn.iocoder.boot</groupId>
@@ -4,6 +4,7 @@ import cn.hutool.core.collection.CollUtil;
 import cn.iocoder.yudao.framework.common.pojo.CommonResult;
 import cn.iocoder.yudao.framework.common.util.collection.MapUtils;
 import cn.iocoder.yudao.framework.common.util.object.BeanUtils;
+import cn.iocoder.yudao.framework.common.util.string.StrUtils;
 import cn.iocoder.yudao.module.im.controller.admin.friend.vo.ImFriendRespVO;
 import cn.iocoder.yudao.module.im.controller.admin.friend.vo.ImFriendUpdateReqVO;
 import cn.iocoder.yudao.module.im.dal.dataobject.friend.ImFriendDO;
@@ -94,6 +95,9 @@ public class ImFriendController {
             ImFriendRespVO vo = BeanUtils.toBean(f, ImFriendRespVO.class);
             MapUtils.findAndThen(userMap, f.getFriendUserId(), user ->
                     vo.setNickname(user.getNickname()).setAvatar(user.getAvatar()));
+            // 备注 / 昵称的拼音，给前端做字母分桶 + 拼音搜索
+            vo.setDisplayNamePinyin(StrUtils.toPinyin(vo.getDisplayName()))
+                    .setNicknamePinyin(StrUtils.toPinyin(vo.getNickname()));
             return vo;
         });
     }
@@ -26,7 +26,10 @@ public class ImFriendRespVO {
     @Schema(description = "好友展示备注（仅自己可见）", example = "老张")
     private String displayName;
-    @Schema(description = "好友状态（0=正常，1=已删除）", example = "0")
+    @Schema(description = "好友展示备注的拼音（小写无空格）", example = "laozhang")
+    private String displayNamePinyin;
+
+    @Schema(description = "好友状态", example = "0")
     private Integer status;
     @Schema(description = "添加好友时间")
@@ -40,6 +43,9 @@ public class ImFriendRespVO {
     @Schema(description = "好友昵称（实时聚合自 AdminUser）", example = "芋道")
     private String nickname;
+    @Schema(description = "好友昵称的拼音（小写无空格）", example = "yudao")
+    private String nicknamePinyin;
+
     @Schema(description = "好友头像（实时聚合自 AdminUser）")
     private String avatar;