Springboot-注解-通用操作日志組件

此組件解決的問題是：
「誰」在「什么時間」對「什么」做了「什么事」

本組件目前針對 Spring-boot 做了 Autoconfig，如果是 SpringMVC许溅，也可自己在 xml 初始化 bean

使用方式

基本使用

maven依賴添加SDK依賴

  // 剛傳到maven倉庫上结啼，如果找不到自己編譯源碼上傳到本地吧
        <dependency>
          <groupId>io.github.mouzt</groupId>
          <artifactId>bizlog-sdk</artifactId>
          <version>1.0.0</version>
        </dependency>

SpringBoot入口打開開關(guān),添加 @EnableLogRecord 注解

tenant是代表租戶的標(biāo)識，一般一個服務(wù)或者一個業(yè)務(wù)下的多個服務(wù)都寫死一個 tenant 就可以

@SpringBootApplication(exclude = DataSourceAutoConfiguration.class)
@EnableTransactionManagement
@EnableLogRecord(tenant = "com.mzt.test")
public class Main {

    public static void main(String[] args) {
        SpringApplication.run(Main.class, args);
    }
}

日志埋點(diǎn)

1. 普通的記錄日志

pefix：是拼接在 bizNo 上作為 log 的一個標(biāo)識抡诞。避免 bizNo 都為整數(shù) ID 的時候和其他的業(yè)務(wù)中的 ID 重復(fù)。比如訂單 ID、用戶 ID 等
bizNo：就是業(yè)務(wù)的 ID庇楞，比如訂單ID揖铜，我們查詢的時候可以根據(jù) bizNo 查詢和它相關(guān)的操作日志
success：方法調(diào)用成功后把 success 記錄在日志的內(nèi)容中
SpEL 表達(dá)式：其中用雙大括號包圍起來的（例如：{{#order.purchaseName}}）#order.purchaseName 是 SpEL表達(dá)式茴丰。Spring中支持的它都支持的。比如調(diào)用靜態(tài)方法天吓，三目表達(dá)式贿肩。SpEL 可以使用方法中的任何參數(shù)

  @LogRecordAnnotation(success = "{{#order.purchaseName}}下了一個訂單,購買商品「{{#order.productName}}」,下單結(jié)果:{{#_ret}}",
              prefix = LogRecordType.ORDER, bizNo = "{{#order.orderNo}}")
  public boolean createOrder(Order order) {
      log.info("【創(chuàng)建訂單】orderNo={}", order.getOrderNo());
      // db insert order
      return true;
  }

此時會打印操作日志 "張三下了一個訂單,購買商品「超值優(yōu)惠紅燒肉套餐」,下單結(jié)果:true"

2. 期望記錄失敗的日志, 如果拋出異常則記錄fail的日志，沒有拋出記錄 success 的日志

    @LogRecordAnnotation(
            fail = "創(chuàng)建訂單失敗龄寞，失敗原因：「{{#_errorMsg}}」",
            success = "{{#order.purchaseName}}下了一個訂單,購買商品「{{#order.productName}}」,下單結(jié)果:{{#_ret}}",
            prefix = LogRecordType.ORDER, bizNo = "{{#order.orderNo}}")
    public boolean createOrder(Order order) {
        log.info("【創(chuàng)建訂單】orderNo={}", order.getOrderNo());
        // db insert order
        return true;
    }

其中的 #_errorMsg 是取的方法拋出異常后的異常的 errorMessage汰规。

3. 日志支持種類

比如一個訂單的操作日志，有些操作日志是用戶自己操作的物邑，有些操作是系統(tǒng)運(yùn)營人員做了修改產(chǎn)生的操作日志溜哮，我們系統(tǒng)不希望把運(yùn)營的操作日志暴露給用戶看到，
但是運(yùn)營期望可以看到用戶的日志以及運(yùn)營自己操作的日志色解，這些操作日志的bizNo都是訂單號茂嗓，所以為了擴(kuò)展添加了類型字段,主要是為了對日志做分類，查詢方便科阎，支持更多的業(yè)務(wù)述吸。

    @LogRecordAnnotation(
            fail = "創(chuàng)建訂單失敗，失敗原因：「{{#_errorMsg}}」",
            category = "MANAGER",
            success = "{{#order.purchaseName}}下了一個訂單,購買商品「{{#order.productName}}」,下單結(jié)果:{{#_ret}}",
            prefix = LogRecordType.ORDER, bizNo = "{{#order.orderNo}}")
    public boolean createOrder(Order order) {
        log.info("【創(chuàng)建訂單】orderNo={}", order.getOrderNo());
        // db insert order
        return true;
    }

4. 支持記錄操作的詳情或者額外信息

如果一個操作修改了很多字段锣笨，但是success的日志模版里面防止過長不能把修改詳情全部展示出來蝌矛，這時候需要把修改的詳情保存到 detail 字段，
detail 是一個 String 错英，需要自己序列化入撒。這里的 #order.toString() 是調(diào)用了 Order 的 toString() 方法。
如果保存 JSON椭岩，自己重寫一下 Order 的 toString() 方法就可以茅逮。

 @LogRecordAnnotation(
            fail = "創(chuàng)建訂單失敗，失敗原因：「{{#_errorMsg}}」",
            category = "MANAGER_VIEW",
            detail = "{{#order.toString()}}",
            success = "{{#order.purchaseName}}下了一個訂單,購買商品「{{#order.productName}}」,下單結(jié)果:{{#_ret}}",
            prefix = LogRecordType.ORDER, bizNo = "{{#order.orderNo}}")
    public boolean createOrder(Order order) {
        log.info("【創(chuàng)建訂單】orderNo={}", order.getOrderNo());
        // db insert order
        return true;
    }

5. 如何指定操作日志的操作人是什么判哥？框架提供了兩種方法

第一種：手工在LogRecord的注解上指定献雅。這種需要方法參數(shù)上有operator

    @LogRecordAnnotation(
            fail = "創(chuàng)建訂單失敗，失敗原因：「{{#_errorMsg}}」",
            category = "MANAGER_VIEW",
            detail = "{{#order.toString()}}",
            operator = "{{#currentUser}}",
            success = "{{#order.purchaseName}}下了一個訂單,購買商品「{{#order.productName}}」,下單結(jié)果:{{#_ret}}",
            prefix = LogRecordType.ORDER, bizNo = "{{#order.orderNo}}")
    public boolean createOrder(Order order, String currentUser) {
        log.info("【創(chuàng)建訂單】orderNo={}", order.getOrderNo());
        // db insert order
        return true;
    }

這種方法手工指定姨伟，需要方法參數(shù)上有 operator 參數(shù)惩琉，或者通過 SpEL 調(diào)用靜態(tài)方法獲取當(dāng)前用戶。

第二種：通過默認(rèn)實(shí)現(xiàn)類來自動的獲取操作人夺荒，由于在大部分web應(yīng)用中當(dāng)前的用戶都是保存在一個線程上下文中的瞒渠，所以每個注解都加一個operator獲取操作人顯得有些重復(fù)勞動良蒸，所以提供了一個擴(kuò)展接口來獲取操作人
框架提供了一個擴(kuò)展接口，使用框架的業(yè)務(wù)可以 implements 這個接口自己實(shí)現(xiàn)獲取當(dāng)前用戶的邏輯伍玖，
對于使用 Springboot 的只需要實(shí)現(xiàn) IOperatorGetService 接口嫩痰，然后把這個 Service 作為一個單例放到 Spring 的上下文中。使用 Spring Mvc 的就需要自己手工裝配這些 bean 了窍箍。

@Configuration
public class LogRecordConfiguration {

    @Bean
    public IOperatorGetService operatorGetService() {
        return () -> Optional.of(OrgUserUtils.getCurrentUser())
                .map(a -> new OperatorDO(a.getMisId()))
                .orElseThrow(() -> new IllegalArgumentException("user is null"));
    }
}

//也可以這么搞：
@Service
public class DefaultOperatorGetServiceImpl implements IOperatorGetService {

    @Override
    public OperatorDO getUser() {
        OperatorDO operatorDO = new OperatorDO();
        operatorDO.setOperatorId("SYSTEM");
        return operatorDO;
    }
}

6. 日志文案調(diào)整

對于更新等方法串纺，方法的參數(shù)上大部分都是訂單ID、或者產(chǎn)品ID等椰棘，
比如下面的例子：日志記錄的success內(nèi)容是："更新了訂單{{#orderId}},更新內(nèi)容為...."纺棺，這種對于運(yùn)營或者產(chǎn)品來說難以理解，所以引入了自定義函數(shù)的功能邪狞。
使用方法是在原來的變量的兩個大括號之間加一個函數(shù)名稱例如 "{ORDER{#orderId}}" 其中 ORDER 是一個函數(shù)名稱祷蝌。只有一個函數(shù)名稱是不夠的,需要添加這個函數(shù)的定義和實(shí)現(xiàn)》浚可以看下面例子
自定義的函數(shù)需要實(shí)現(xiàn)框架里面的IParseFunction的接口巨朦，需要實(shí)現(xiàn)兩個方法：

functionName() 方法就返回注解上面的函數(shù)名；
apply()函數(shù)參數(shù)是 "{ORDER{#orderId}}"中SpEL解析的#orderId的值剑令，這里是一個數(shù)字1223110糊啡，接下來只需要在實(shí)現(xiàn)的類中把 ID 轉(zhuǎn)換為可讀懂的字符串就可以了，
一般為了方便排查問題需要把名稱和ID都展示出來吁津，例如："訂單名稱（ID）"的形式棚蓄。

這里有個問題：加了自定義函數(shù)后，框架怎么能調(diào)用到呢腺毫？
答：對于Spring boot應(yīng)用很簡單癣疟，只需要把它暴露在Spring的上下文中就可以了挣柬，可以加上Spring的 @Component 或者 @Service 很方便??潮酒。Spring mvc 應(yīng)用需要自己裝配 Bean。

    // 沒有使用自定義函數(shù)
    @LogRecordAnnotation(success = "更新了訂單{{#orderId}},更新內(nèi)容為....",
            prefix = LogRecordType.ORDER, bizNo = "{{#order.orderNo}}",
            detail = "{{#order.toString()}}")
    public boolean update(Long orderId, Order order) {
        return false;
    }

    //使用了自定義函數(shù)邪蛔，主要是在 {{#orderId}} 的大括號中間加了 functionName
    @LogRecordAnnotation(success = "更新了訂單ORDER{#orderId}},更新內(nèi)容為...",
            prefix = LogRecordType.ORDER, bizNo = "{{#order.orderNo}}",
            detail = "{{#order.toString()}}")
    public boolean update(Long orderId, Order order) {
        return false;
    }

    // 還需要加上函數(shù)的實(shí)現(xiàn)
    @Component
    public class OrderParseFunction implements IParseFunction {
        @Resource
        @Lazy //為了避免類加載順序的問題 最好為Lazy急黎，沒有問題也可以不加
        private OrderQueryService orderQueryService;
        
        @Override 
        public String functionName() {
            //  函數(shù)名稱為 ORDER
            return "ORDER";
        }
    
        @Override
        //這里的 value 可以吧 Order 的JSON對象的傳遞過來，然后反解析拼接一個定制的操作日志內(nèi)容
        public String apply(String value) {
            if(StringUtils.isEmpty(value)){
                return value;
            }
            Order order = orderQueryService.queryOrder(Long.parseLong(value));
            //把訂單產(chǎn)品名稱加上便于理解侧到，加上 ID 便于查問題
            return order.getProductName().concat("(").concat(value).concat(")");
        }
    }

7. 日志文案調(diào)整使用 SpEL 三目表達(dá)式

    @LogRecordAnnotation(prefix = LogRecordTypeConstant.CUSTOM_ATTRIBUTE, bizNo = "{{#businessLineId}}",
            success = "{{#disable ? '停用' : '啟用'}}了自定義屬性{ATTRIBUTE{#attributeId}}")
    public CustomAttributeVO disableAttribute(Long businessLineId, Long attributeId, boolean disable) {
        return xxx;
    }

框架的擴(kuò)展點(diǎn)

重寫OperatorGetServiceImpl通過上下文獲取用戶的擴(kuò)展勃教，例子如下

@Service
public class DefaultOperatorGetServiceImpl implements IOperatorGetService {

    @Override
    public Operator getUser() {
         return Optional.ofNullable(UserUtils.getUser())
                        .map(a -> new Operator(a.getName(), a.getLogin()))
                        .orElseThrow(()->new IllegalArgumentException("user is null"));
       
    }
}

ILogRecordService 保存/查詢?nèi)罩镜睦?使用者可以根據(jù)數(shù)據(jù)量保存到合適的存儲介質(zhì)上，比如保存在數(shù)據(jù)庫/或者ES匠抗。自己實(shí)現(xiàn)保存和刪除就可以了

也可以只實(shí)現(xiàn)保存的接口故源，畢竟已經(jīng)保存在業(yè)務(wù)的存儲上了，查詢業(yè)務(wù)可以自己實(shí)現(xiàn)汞贸，不走 ILogRecordService 這個接口绳军，畢竟產(chǎn)品經(jīng)理會提一些千奇百怪的查詢需求印机。

@Service
public class DbLogRecordServiceImpl implements ILogRecordService {

    @Resource
    private LogRecordMapper logRecordMapper;

    @Override
    @Transactional(propagation = Propagation.REQUIRES_NEW)
    public void record(LogRecord logRecord) {
        log.info("【logRecord】log={}", logRecord);
        LogRecordPO logRecordPO = LogRecordPO.toPo(logRecord);
        logRecordMapper.insert(logRecordPO);
    }

    @Override
    public List<LogRecord> queryLog(String bizKey, Collection<String> types) {
        return Lists.newArrayList();
    }

    @Override
    public PageDO<LogRecord> queryLogByBizNo(String bizNo, Collection<String> types, PageRequestDO pageRequestDO) {
        return logRecordMapper.selectByBizNoAndCategory(bizNo, types, pageRequestDO);
    }
}

IParseFunction 自定義轉(zhuǎn)換函數(shù)的接口，可以實(shí)現(xiàn)IParseFunction 實(shí)現(xiàn)對LogRecord注解中使用的函數(shù)擴(kuò)展
例子：

@Component
public class UserParseFunction implements IParseFunction {
    private final Splitter splitter = Splitter.on(",").trimResults();

    @Resource
    @Lazy
    private UserQueryService userQueryService;

    @Override
    public String functionName() {
        return "USER";
    }

    @Override
    // 11,12 返回 11(小明门驾，張三)
    public String apply(String value) {
        if (StringUtils.isEmpty(value)) {
            return value;
        }
        List<String> userIds = Lists.newArrayList(splitter.split(value));
        List<User> misDOList = userQueryService.getUserList(userIds);
        Map<String, User> userMap = StreamUtil.extractMap(misDOList, User::getId);
        StringBuilder stringBuilder = new StringBuilder();
        for (String userId : userIds) {
            stringBuilder.append(userId);
            if (userMap.get(userId) != null) {
                stringBuilder.append("(").append(userMap.get(userId).getUsername()).append(")");
            }
            stringBuilder.append(",");
        }
        return stringBuilder.toString().replaceAll(",$", "");
    }
}

變量相關(guān)

LogRecordAnnotation 可以使用的變量出了參數(shù)也可以使用返回值#_ret變量射赛，以及異常的錯誤信息#_errorMsg，也可以通過SpEL的 T 方式調(diào)用靜態(tài)方法噢

帶擴(kuò)展

實(shí)現(xiàn)一個 Log的 Context奶是，可以解決方法參數(shù)中沒有的變量但是想使用的問題楣责，初步想法是可以通過在方法中 add 變量的形式實(shí)現(xiàn)，很快就可以實(shí)現(xiàn)了 ??

注意點(diǎn)：

?? 整體日志攔截是在方法執(zhí)行之后記錄的聂沙，所以對于方法內(nèi)部修改了方法參數(shù)之后秆麸，LogRecordAnnotation 的注解上的 SpEL 對變量的取值是修改后的值哦～

源碼：

https://github.com/mouzt/mzt-biz-log

SpringBoot-可使用變量的注解型「操作日志」組件

SpringBoot-可使用變量的注解型「操作日志」組件

Springboot-注解-通用操作日志組件

使用方式

基本使用

maven依賴添加SDK依賴

SpringBoot入口打開開關(guān),添加 @EnableLogRecord 注解

日志埋點(diǎn)

1. 普通的記錄日志

2. 期望記錄失敗的日志, 如果拋出異常則記錄fail的日志，沒有拋出記錄 success 的日志

3. 日志支持種類

4. 支持記錄操作的詳情或者額外信息

5. 如何指定操作日志的操作人是什么判哥？框架提供了兩種方法

6. 日志文案調(diào)整

7. 日志文案調(diào)整使用 SpEL 三目表達(dá)式

框架的擴(kuò)展點(diǎn)

變量相關(guān)

帶擴(kuò)展

注意點(diǎn)：

源碼：

SpringBoot-可使用變量的注解型「操作日志」組件

Springboot-注解-通用操作日志組件

使用方式

基本使用

maven依賴添加SDK依賴

SpringBoot入口打開開關(guān),添加 @EnableLogRecord 注解

日志埋點(diǎn)

1. 普通的記錄日志

2. 期望記錄失敗的日志, 如果拋出異常則記錄fail的日志，沒有拋出記錄 success 的日志

3. 日志支持種類

4. 支持記錄操作的詳情或者額外信息

5. 如何指定操作日志的操作人是什么判哥？ 框架提供了兩種方法

6. 日志文案調(diào)整

7. 日志文案調(diào)整 使用 SpEL 三目表達(dá)式

框架的擴(kuò)展點(diǎn)

變量相關(guān)

帶擴(kuò)展

注意點(diǎn)：

源碼：

5. 如何指定操作日志的操作人是什么判哥？框架提供了兩種方法

7. 日志文案調(diào)整使用 SpEL 三目表達(dá)式