### Lombok插件安裝 - 項目使用 [Lombok](https://projectlombok.org/) 插件簡化開發，請自行在編譯器中安裝，不安裝會報錯但不影響運行，常用注解說明： - `@Data`：自動生成get、set等方法 - `@Slf4j`：日志打印可直接使用`log.info()`等 - 更多詳見文檔 [開發經驗章節](http://www.hmoore.net/exrick/xboot/1684587) 部分 ### 配置文件加密 - 配置文件可使用Jasypt加密，可到 `cn.exrick.xboot.common` 包中找到 JasyptUtil 工具類生成加解密結果，當檢測到格式為`ENC(xxx)`時會自動解密，當然也可直接明文（生產環境中可通過環境變量、命令行等形式進行設置） ```yaml # 配置文件加密key 生產環境中可通過環境變量、命令行等形式進行設置 jasypt: encryptor: password: xboot spring: # 數據源 datasource: # Jasypt加密 可到common-utils中找到JasyptUtil加解密工具類生成加密結果 格式為ENC(加密結果) password: ENC(F4B0s6u9xcDw3V+P0qC4CA==) ``` ### 啟用Elasticsearch與配置日志記錄位置 - 啟用Elasticsearch，操作日志使用ES或數據庫記錄配置 ```yaml spring: # Elasticsearch data: elasticsearch: # 啟用 repositories: enabled: true autoconfigure: exclude: # 取消排除 # - org.springframework.boot.autoconfigure.data.elasticsearch.ReactiveElasticsearchRestClientAutoConfiguration xboot: # 日志記錄方式 設置為true logRecord: es: true ``` ### 操作日志注解使用 - 日志注解使用`@SystemLog(description="操作日志名稱", type=日志類型)` - 日志類型type枚舉類相關候選值：`OPERATION`（默認，用戶操作相關）、`LOGIN`（用戶登錄），可自定義添加修改 ### 接口相關 - 為方便前端配置代理，所有接口建議以統一路徑例如“/xboot”開頭（當然后端也可配置`context-path`） - 登錄成功后前端在返回的`result`字段中保存token令牌集合（因登錄接口已添加圖片驗證碼驗證，需帶上圖片驗證碼所需參數，具體使用詳見文檔 [驗證碼開發使用](http://www.hmoore.net/exrick/xboot/1136968) 或 [接口文檔使用及認證](http://www.hmoore.net/exrick/xboot/1027473) 部分） <img src="https://ooo.0o0.ooo/2019/02/04/5c581d77f2cfc.png" width="600px"/> - 之后的請求中請在header或參數中添加該token參數即可，默認KEY為`accessToken`（`SecurityConstant`中可修改） <img src="https://ooo.0o0.ooo/2019/02/04/5c581d78061b4.png" width="600px"/> ### 無狀態風格Token令牌交互相關配置 ```yaml xboot: token: # 默認為true，token將存入redis，并具有單設備登錄、自動刷新token過期時間功能 設為false使用JWT交互 redis: true # 是否開啟單設備登陸 一個賬號僅支持同時一臺設備登錄 僅當token交互方式為redis時生效 sdl: false # token中存儲用戶權限數據 開啟后可避免每次請求再獲取用戶權限，但有可能導致編輯權限菜單后無法讀取到最新權限數據（需用戶重新登錄） storePerms: true # token過期時間 redis模式有請求自動刷新過期時間（分鐘） tokenExpireTime: 60 # 用戶選擇 保存登錄狀態/記住我 對應token過期時間 不會自動刷新過期時間（天） saveLoginTime: 7 # 限制用戶登陸錯誤次數（次） loginTimeLimit: 10 # 錯誤超過次數后多少分鐘后才能繼續登錄（分鐘） loginAfterTime: 10 ``` ### 無需登錄認證接口配置 - 忽略鑒權url配置（不需要登錄認證 開放的接口 支持通配符） ``` # 忽略鑒權url ignored: urls: - /xboot/auth/login ``` ### 限流配置 - 分布式限流(基于Redis令牌桶算法) - 全局限流 ```yaml xboot: # 全局限流 ratelimit: enable: true # 每1秒內 timeout: 1000 # 總限制100個請求 limit: 100 # IP限流 iplimit: enable: true # 每1秒內 timeout: 1000 # 每個ip限制15個請求 limit: 15 ``` - 指定方法限流注解（詳見注解源碼注釋） ```java /** * name 自定義限流切入點名稱 類型long 默認類的引用路徑+方法名 * rate 限流速率（時間間隔內最大請求個數） 類型long 默認5 * rateInterval 速率間隔 單位毫秒 類型long 默認1000 * ipLimit 是否啟用IP限流（加上IP作為name標識）類型boolean 默認false */ @RateLimiter(rate = 1, rateInterval = 5000) ``` - 自定義多維度IP、uid限流示例（可選基于內存的令牌桶算法） ```java @Autowired private RedisRaterLimiter redisRaterLimiter; // IP限流 1秒限1個請求 基于Redis的令牌桶算法 String token = redisRaterLimiter.acquireByRedis(ip, 1, 1000); // 基于內存的令牌桶算法 每秒限1個請求 String token = redisRaterLimiter.acquireByGuava(1); if (StrUtil.isBlank(token)) { throw new XbootException("你手速怎么這么快，請點慢一點"); } ``` - 配置無需限流的資源或接口 ```yml # 忽略url ignored: # 限流及黑名單不攔截的路徑 limitUrls: - /**/*.js - /**/*.css - /**/*.png - /**/*.ico ``` ### 文件上傳大小限制 ```yml xboot: # 文件大小上傳配置 單位MB maxUploadFile: 5 ``` ### 同步鎖使用 - 分布式同步鎖 ```java @Autowired private RedisLockTemplate redisLockTemplate; redisLockTemplate.execute("訂單流水號", 3, TimeUnit.SECONDS, new Callback() { @Override public Object onGetLock() throws InterruptedException { // TODO 獲得鎖后要做的事 log.info("生成訂單流水號"); return null; } @Override public Object onTimeout() throws InterruptedException { // TODO 未獲取到鎖（獲取鎖超時）后要做的事 log.info("oops 沒拿到鎖"); return null; } }); ``` ### 后端代碼生成 - 后端代碼生成方法在 `cn.exrick.xboot.generator` 包中的 `XbootGenerator.java` 或`XbootMPGenerator.java` 工具類，支持JPA或Mybatis-Plus代碼生成，修改好生成類配置后運行主函數main方法即可生成相關代碼，別忘了在實體類中添加相關字段，運行項目后將自動生成數據庫表，詳見文檔[代碼生成部分](http://www.hmoore.net/exrick/xboot/1021397) ### Spring緩存注解 - 配置失效過期時間 ```yml xboot: # 使用Spring @Cacheable注解失效時間 cache: # 緩存過期時間 Duration類型 D–天 H小時 M–分鐘 S–秒 永久不過期設為非正值 timeToLive: 15D ``` - 使用示例 ```java @CacheConfig(cacheNames = "user") public interface UserService extends XbootBaseService<User,String> { @Cacheable(key = "#username") User findByUsername(String username); } ``` - 刪除刷新注解 `@CacheEvict(key = "#u.username")` - 注意手動刪除刷新緩存時key為：`user::username` ### Quartz定時任務使用 - 在`cn.exrick.xboot.modules.quartz.jobs`包下編寫好你的定時任務類，參考代碼中已有2個定時任務Job示例 - 啟動應用在后臺頁面“定時任務”菜單添加配置你寫的的定時任務類保存成功后將開始執行 - 注意在Quartz中注入Bean需使用構造setter注入方式或使用`SpringUtil.getBean("你的類名")`工具類 ### Spring Security官方推薦權限管理 - Spring Security官方推薦[注解表達式權限管理](https://docs.spring.io/spring-security/site/docs/5.4.1/reference/html5/#el-common-built-in)（當然你可以在XBoot權限菜單中動態配置，更佳靈活） * @PreAuthorize("isAuthenticated()") * @PreAuthorize("hasAuthority('read')") * @PreAuthorize("hasAnyAuthority('read', 'write')") * @PreAuthorize("hasRole('ADMIN')") * @PreAuthorize("hasAnyRole('ADMIN', 'USER')") * @PreAuthorize("hasRole('ADMIN') and hasRole('USER')") * @PreAuthorize("hasRole('ADMIN') or hasRole('USER')") ### Spring自帶定時：`@Scheduled(cron="cron表達式")` ### Spring異步：`@Async` ### 參數校驗注解 - 需要校驗的實體類字段或Controller請求參數加上JSR校驗注解后，Controller請求參數前加上`@Valid`注解。注意對于`@PathVariable`或`@RequestParam`參數的校驗，記得在Controller類上添加`@Validated`注解。已全局封裝`參數、@ResponseBody`參數校驗異常處理 - 常用JSR/Jakarta Bean Validation提供的校驗注解: - @NotNull(message=) 必須不能為 null - @Email(message=) 必須為郵箱格式 - @Size(max=, min=) 大小必須在指定的范圍內 - @Pattern(regex=, message=) 必須符合指定的正則表達式 - 更多及使用方法詳見文檔[告別996-參數校驗部分](http://www.hmoore.net/exrick/xboot/1684588) ### MySQL數據庫存儲Emoji - 如果需要存儲Emoji表情、不常用的漢字，以及任何新增的Unicode字符，需要兼容四字節Unicode的字符集`utf8mb4`。當然可修改數據庫所有編碼默認為`utf8mb4`，為了節省空間，建議請修改具體需要的字符型字段的編碼及排序規則為`utf8mb4`即可，如： ```sql ALTER TABLE 表名 MODIFY COLUMN 列名 varchar(256) CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci; ```