# wshoto-ocean

**Repository Path**: huangth123/wshoto-ocean

## Basic Information

- **Project Name**: wshoto-ocean
- **Description**: 巨量引擎定制开发模块
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 1
- **Created**: 2021-12-20
- **Last Updated**: 2022-10-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# wshoto-ocean

## 介绍

> 本示例不作为脚手架使用，本示例只定义工程结构规范，作为模板工程使用，统一spring cloud版本，spring boot版本，spring版本及spring boot相关依赖版本等，统一异常规范，统一日志规范，统一返回结果处理及接口及开发规约定义。

本示例除提供规范说明以外，也提供了统一异常处理的能力，统一返回结果处理的能力，统一日志规范输出能力，因此可将本示例直接拷贝，按规范创建自己的业务模块直接使用
同时也提供了部分常用组件的starter包，starter包统一放在wshoto-manager下，starter包的作用范围需界定清楚
该工程结构可自有灵活拆分组合，一方包可自行斟酌，二方包必须上传maven伺服后引入工程使用，严格控制二方包版本及升级说明，暂无对外提供三方包的需求 使用说明：
如需创建业务模块，需项目或产品线负责人着手创建，尽量避免开发人员自行创建，即便由开发人员自行创建，项目或产品线负责人也需要审核工程结构，命名规范日志配置，maven依赖等
创建工程时，需将common包彻底移除，引入Maven伺服中上传的common二方包使用 **禁止开发人员自行修改common包结构及内容，严禁开发人员在任何地方以任何形式私自定义使用状态码作为接口返回内容**
如需要新增状态码，必须申报到项目或产品负责人，有项目或产品负责人提交申请，审批通过，由专人统一维护增加状态码，升级common二方包

更为详细的规范均在示例代码中有详细阐述

[【腾讯文档】Wshoto工程架构](https://docs.qq.com/doc/DWEVEaUlNVkFXVE5u)

> 关于maven伺服权限配置： 须在本地maven setting.xml中加入以下配置

```xml
<servers>
  <server>
    <id>wshoto-nexus</id>
    <username>wshoto</username>
    <password>wshoto@2020</password>
  </server>
</servers>
```

> 包发布者需在本地maven setting.xml server配置中额外加入以下配置

```xml

<servers>
  <server>
    <id>wshoto-nexus-releases</id>
    <username>分配的账号</username>
    <password>分配的账号密码</password>
  </server>
  <server>
    <id>wshoto-nexus-snapshots</id>
    <username>分配的账号</username>
    <password>分配的账号密码</password>
  </server>
</servers>
```

> Docker Registry统一使用腾讯云TCR。
>
> Docker Registry地址：wshoto.tencentcloudcr.com/qwgj，仅支持内网访问

## 工程启动脚本示例：

Docker启动脚本示例：

```sh
docker run -d --restart=always --net=host --name wshoto-XXXX \
-v /data/wshoto:/data/wshoto \
-e AGENT_OPTS='-Dskywalking.agent.service_name=XXXX-server -Dskywalking.collector.backend_service=X.X.X.X:11800' \
-e PARAMS='--spring.profiles.active=uat --spring.cloud.nacos.server-addr=X.X.X.X:8848' \
wshoto.tencentcloudcr.com/qwgj/wshoto-ocean:latest
```

Bash脚本示例：

```sh
#!/bin/bash
echo "删除旧服务容器"
docker rm -f wshoto-XXXX
echo "删除旧镜像"
docker rmi -f wshoto.tencentcloudcr.com/qwgj/wshoto-XXXX:latest
echo "TCR登录"
docker login wshoto.tencentcloudcr.com --username 100014537081 --password eyJhbGciOiJSUzI1NiIsImtpZCI6IlBSRUk6VDZZSzpQTzNNOjRRVUc6VlJFTjo2UjZKOkxJNEQ6UVVERDpKWk9aOksyN0Q6R0tXMzoySDVLIn0.eyJvd25lclVpbiI6IjEwMDAxNDUzNzA4MSIsIm9wZXJhdG9yVWluIjoiMTAwMDE0NTM3MDgxIiwidG9rZW5JZCI6ImMxZGQwbGk4ajVqcGtiMHJ0anAwIiwiZXhwIjoxOTMxOTI0MzEwLCJuYmYiOjE2MTY1NjQzMTAsImlhdCI6MTYxNjU2NDMxMH0.RVzJ_iwbbRF0sF1N5E05JcWtt5qlcsH1kGl--Nt0UUiBEfbJZsVYyCKRrCjRhk_J9oCQl2sriak2BTgVL13AqFR-DWsrxGlLTcTbi_E2JcrBaMb1PZ3YEX6ggTWy7OD98OaqbLWfSi2Dd8mjAWHyzImvrmCh6wNoReOGLTnm0fQlNyorba_KyuHw40t8A0b0pzLvRnWPII7R9IwG8BP5VyqJMxGhJhcPPi2hXV1wjO3LRp2aZ0kRLRFevBDkyOGCpXr3kSpb6IVGOOGE1EGSIRsXlYc8f177romdqBEopFcpPCeZauCkCPMRzMYvMdj6wzyR0MASmCw044S7YSJjCg
echo "Docker启动"
docker run -d --restart=always --net=host --name wshoto-XXXX -v /data/wshoto:/data/wshoto -e AGENT_OPTS='-Dskywalking.agent.service_name=XXXX-server -Dskywalking.collector.backend_service=X.X.X.X:11800' -e PARAMS='--spring.profiles.active=uat --spring.cloud.nacos.server-addr=X.X.X.X:8848' wshoto.tencentcloudcr.com/qwgj/wshoto-ocean:latest
```

TKE发布Yaml文件示例：

```yaml
apiVersion: v1
kind: Namespace
metadata:
  name: test
---
apiVersion: apps/v1
kind: Deployment
metadata:
  labels:
    app: wshoto-ocean
  name: wshoto-ocean
  namespace: test
spec:
  revisionHistoryLimit: 3
  replicas: 1
  selector:
    matchLabels:
      app: wshoto-ocean
  template:
    metadata:
      labels:
        app: wshoto-ocean
    spec:
      containers:
        - image: wshoto.tencentcloudcr.com/qwgj/wshoto-ocean:test
          imagePullPolicy: Always
          env:
            - name: "AGENT_OPTS"
              value: "-Dskywalking.agent.service_name=ocean-server -Dskywalking.collector.backend_service=skywalking-oap.test.svc.cluster.local:11800"
            - name: "PARAMS"
              value: "--spring.profiles.active=uat --spring.cloud.nacos.server-addr=nacos.test.svc.cluster.local:8848"
            - name: NODE_NAME
              valueFrom:
                fieldRef:
                  apiVersion: v1
                  fieldPath: spec.nodeName
          name: wshoto-ocean
          resources:
            requests:
              cpu: 1000m
              memory: 4Gi
            limits:
              cpu: 1000m
              memory: 4Gi
          securityContext:
            runAsUser: 0
          terminationMessagePath: /test/termination-log
          terminationMessagePolicy: File
          volumeMounts:
            - mountPath: /data/wshoto
              name: logpath
            - name: timezone
              mountPath: /etc/localtime
      dnsPolicy: ClusterFirst
      restartPolicy: Always
      schedulerName: default-scheduler
      securityContext: { }
      terminationGracePeriodSeconds: 30
      volumes:
        - hostPath:
            path: /data/wshoto
            type: ''
          name: logpath
        - name: timezone
          hostPath:
            path: /etc/localtime
---
apiVersion: v1
kind: Service
metadata:
  labels:
    name: wshoto-ocean
  name: wshoto-ocean
  namespace: test
spec:
  ports:
    - name: server
      port: 7000
      protocol: TCP
      targetPort: 7000
  selector:
    app: wshoto-ocean
  sessionAffinity: None
  type: ClusterIP
```

Helm发布示例:

```sh

```

<br/>

## 2021/2/12更新 信息安全建设-配置文件加密方式

- bootstrap.yml配置文件中增加配置如下：

```yaml
jasypt:
    encryptor:
        algorithm: PBEWithMD5AndDES
        iv-generator-classname: org.jasypt.iv.NoIvGenerator
        password: wshoto@2020
```

- 手动生成要加密的密码密文:

```sh
java -cp jasypt-1.9.3.jar org.jasypt.intf.cli.JasyptPBEStringEncryptionCLI input="wshoto@2020" password=wshoto@2020 algorithm=PBEWithMD5AndDES
```

> Tips:input为要加密的字符串，password与bootstrap.yml配置文件中jasypt配置的password保持一致，加密方式采用PBEWithMD5AndDES

- 在需要配置密码的配置文件中替换原明文密码为ENC(此处为生成的密文)

<br/>

## 2021/3/8更新 统一日志，统一监控接入规范升级

- **引入monitor-boot-starter、log-boot-starter、trace-boot-starter包**
- **修改bootstrap.yml配置文件**
  - 删除logback配置
    ```yaml
    # logback
    logging:
      config: classpath:logback-wshoto.xml
    ```
  - 删除日志路径配置
    ```yaml
    info:    
      wshoto:
          logging:
              path: /data/wshoto/logs
    ```
  - 删除端点监控配置
    ```yaml
    ## spring-boot-actuator配置
    management:
      endpoints:
          web:
              exposure:
                  include: '*'
      endpoint:
          health:
              show-details: always
    ```
  - 在bootstrap.yml同级目录下创建application.yml并作如下配置
    ```
    spring:
      profiles:
          include: monitor,log,trace
    ```

<br/>

## 2021/3/24更新 基础镜像发布，Skywalking统一接入规范

```dockerfile
##底层镜像必须依赖wshoto.tencentcloudcr.com/qwgj/wshoto-base:latest
FROM wshoto.tencentcloudcr.com/qwgj/wshoto-base:latest
MAINTAINER Lee

##添加你的工程编译后的jar包并修改名称统一为app.jar
ADD target/ocean_app.jar /app.jar

##暴露启动入口，统一格式如下
ENTRYPOINT ["sh","-c","java $JAVA_OPTS -javaagent:/agent/skywalking-agent.jar $AGENT_OPTS -jar /app.jar $PARAMS"]
```

> Tips:无特殊需要，不得私自篡改底层依赖镜像，不得私自新增环境变量参数，**严禁覆盖JAVA_OPTS，AGENT_OPTS，PARAMS变量**

## 2021/4/16更新 APIFirst定义规范

新增APIFirst定义规范，统一采用protobuf作为API定义描述，示例定义参见wshoto-proto工程，proto转openapi3描述方式：

```sh
#!/bin/sh
docker run --rm -it -v ${PWD}:/data -w /data locklee/pl-proto-tool:latest protoc -I. \
--openapiv2_out . \
--openapiv2_opt logtostderr=true \
--openapiv2_opt json_names_for_fields=false *.proto
```

> Tips:,具备docker运行环境，替换${PWD}为你当前工程的下的.proto文件夹路径，替换*.proto为你要转换的proto文件名
>
> 接口描述预览工具地址：swagger-editor.wshoto.com

## 2021/4/26更新 日志规范调整

- logback无侵入性植入skywalking追踪信标，统一ELK与Skywalking TraceId
- 无需代码修改，重新编译工程打包发布即可
- 适用范围，接入log-boot-starter包的所有工程

## 2021/4/29更新 审计日志接入

新增审计日志切面、注解、日志Topic，日志规范，使用方式及应用范围：

开启审计日志，配置文件中增加：

```yaml
wshoto:
  audit-log:
    enable: true
```

使用方式，Controller接口上增加@AuditLog注解,示例如下：

```java
@AuditLog(type = AuditLog.OperationType.SAVE, operation = "'注册了应用'+#appRegisterReq.appName")
@ApiOperation("注册应用")
@PutMapping("/appRegister")
public String appRegister(@RequestBody @Validated AppRegisterReq appRegisterReq, HttpServletRequest request) {
    appService.appRegister(appRegisterReq);
    return ResultUtils.success().toString();
}
```

> 租户信息通过Header中x-tenant-header自动获取
>
> 用户ID通过Header中x-userid-header自动获取
>
> operation描述信息遵循spEL表达式，以#开头作为spEL表达式起始标识
>
> type（操作类型）包含四种，枚举值为DELELE,SAVE,UPDATE,LOGIN

**详细使用实例参见模板工程代码**

## 2021/4/29更新 新增XStream工具

> 包信息说明，路径位于wshoto-framework-common下com.wshoto.framework.common.xstream包下
>
> - converter包提供常用扩展转换器
> - XStreamInitializer用于获取XStreem实例（不建议单独使用，特殊场景必须使用，一定要针对每种转换类型单例使用）
> - XStreamTransformer用于序列化和反序列化xml字符串（建议直接使用该方式，XStreem交由XStreamTransformer自行维护）

使用示例：

```java
@Data
@XStreamAlias("xml")
public class Message implements Serializable {

  @XStreamAlias("Id")
  @XStreamConverter(value = LongConverter.class)
  private Long id;

  @XStreamAlias("User")
  private User user;

  @Data
  public static class User implements Serializable {

    @XStreamAlias("Name")
    private String name;

    @XStreamAlias("Sex")
    private String sex;
  }
}
```

```xml
<xml>
  <Id>1</Id>
  <User>
    <Name>张三</Name>
    <Sex>男</Sex>
  </User>
</xml>
```

```java
public static void main(String[] args) {
        String xml = "<xml><Id>1</Id><User><Name>张三</Name><Sex>男</Sex></User></xml>";
        Message message = XStreamTransformer.fromXml(Message.class,xml);
        System.out.println(JSONObject.toJSONString(message));
        }
```

## 2021/05/07 代码生成器首发

新增代码生成器，根据swagger描述文件生成工程，swagger描述文件从proto描述文件转换，具体定义与转换方式参见2021/4/16更新说明，swagger生成工程代码使用方式：

```sh
docker run --rm -it -v ${PWD}:/data -e SERVICE_NAME="xxx" locklee/wshoto-generator:latest
```

> Tips:具备docker运行环境，替换${PWD}为你的swagger文件夹路径，swagger文件映射容器中固定名称为swagger.json，生成工程详见${PWD}目录下code文件夹
>
> - **相同url前缀的接口会生成到同一个JAVA类中**
> - **接口中定义的返回值类型，将作为service层返回值类型使用**

## 2021/05/12 代码生成器更新

* 新增SERVICE_PORT参数 
* 新增Kubernetes部署脚本模板生成
* 新增Tekton pipeline模板生成 
* 新增 "-"连接多级服务名支持，例：-e SERVICE_NAME="user-front"，不超过两级，即不超过两个名词连接
swagger生成工程代码使用方式：

```sh
docker run --rm -it -v ${PWD}:/data -e SERVICE_NAME="xxx" -e SERVICE_PORT="xxx" locklee/wshoto-generator:latest
```

> Tips:具备docker运行环境，替换${PWD}为你的swagger文件夹路径，swagger文件映射容器中固定名称为swagger.json，生成工程详见${PWD}目录下code文件夹