Weixin

理解为这是一个SDK库，被别的项目路由注册，或者调用其service方法，从而实现微信相关业务...

一、技术选型

开发工具

语言/框架/类库

数据库

脚本工具

二、项目结构

/
├── api                   对外接口：接口定义
│   └── weixin_v1             对外提供服务的输入/输出数据结构定义，包含多主体接口定义。
│       ├── weixin_consumer_v1        Weixin消费者相关接口。
│       ├── weixin_merchant_v1        Weixin商户相关接口。
│       ├── weixin_third_v1           Weixin第三方应用相关接口。
│       └── gateway.go        网关相关：回调及消息接收/异步通知接口。
├── database          迁移脚本：数据库脚本及迁移或升级脚本
├── example           运行例子：当前组件模块用于测试调试启动入口文件，启动所需文件示例。
│   ├── internal          组件逻辑：组件逻辑存放目录。通过internal特性对外部隐藏可见性。
│       └── boot          权限初始化：权限树等初始化。
│   ├── ...           示例文件：适配company所需示例文件。
│   └── main.go       入口指令：启动文件，当前作为业务项目引用应用的参考。
├── hack              工具脚本：存放组件开发工具、脚本等内容。例如，CLI工具的配置，各种shell/bat脚本等文件
│   └──   tpls           模板文件：包含dao，do，entity生成的模板，一般配合Makefile使用
├── docs              说明文档：业务流程图 + 接口逻辑实现图。
├── i18n              国际化输出：国际化输出文件
├── internal          组件逻辑：组件逻辑存放目录。通过internal特性对外部隐藏可见性。
│   └── logic         模块封装：组件逻辑封装管理。
│       ├── gateawy            Weixin网关及数据库基础逻辑代码。
│       ├── internal           Weixin拓展逻辑代码。
│           └── aliyun         Weixin拓展逻辑代码。
│       └── merchant           Weixin商户基本操作逻辑代码。
├── manifest          交付清单：包含程序编译、部署、运行、配置的文件。
│   └── config        配置管理：配置文件存放目录。
├── resource         静态资源：静态资源文件。这些文件往往可以通过 资源打包/镜像编译 的形式注入到发布文件中。
├── utility           实用类库：一般以独立文件形式的通用类库
├── weixin_consts              常量定义：组件专用常量或公共类型及变量定义。
├── weixin_controller          接口处理：接收/解析用户输入参数的入口/接口层。
│   ├── merchant          Weixin商户基本操作。
│   └── xxx.go            Weixin数据库基础表操作及网关通知消息等。
├── weixin_model          结构模型：数据结构管理模块，管理数据实体对象，以及输入与输出数据结构定义。
│   ├── weixin_dao           数据访问：数据访问对象，这是一层抽象对象，用于和底层数据库交互，仅包含最基础的 CURD 方法
│   ├── weixin_do            领域对象：用于dao数据操作中业务模型与实例模型转换，由工具维护，用户不能修改。
│   ├── weixin_entity        数据模型：数据模型是模型与数据集合的一对一关系，由工具维护，用户不能修改。
│   ├── weixin_enum          枚举定义：枚举类型及变量定义。
│   └── weixin_hook          Hook定义：钩子函数定义。
├── weixin_service        模块接口：用于组件解耦的接口定义层。具体的接口实现在logic中进行注入。
│   ├── gateawy.go            Weixin网关及数据库基础。
│   └── merchant.go           Weixin商户基本操作。
├── .env              环境配置：权限最高的配置文件。
├── .gitignore        Git忽略：git提交忽略文件定义。
├── go.mod            依赖管理：使用Go Module包管理的依赖描述文件。
├── Makefile          Make工具：使用自定义模版等实现gf工具的封装&替换配置文件。
└── weixin.go         组件入口

weixin-library 理解为这是一个SDK库，项目大部分实现是基于第三方应用代商家发起Api调用

特性：

封装了Weixin网关，用于接收和发送消息。
封装了Weixin小程序开发管理Api
实现了Weixin 授权、登陆、支付、分账、转账等...
模块明确分为第三方应用、商家、消费者三个对象

gateway 主要用于记录和服务商相关操作
merchant 主要记录和商家有关，例如一些商家消息的hook注册，
internal 主要用于拓展SDK所不具备。票据例外
...

描述：

接口包含两部分：接口定义（api）+ 接口实现（controller）

服务包含两部分：模型结构（model）+ 服务接口（service）
负责接收并响应调用的输入与输出，包括对输入参数的过滤、转换、校验，对输出数据结构的维护，并调用 service 实现业务逻辑处理。

三、项目编译/运行

前言：

编译后执行必须文件如下

i18n目录需要，里头包含项目所需国际化输出文件
manifest/config/config.yaml 配置文件
hack/config.yaml 配置文件，用于配置gf dao生成数据模型表（可选）
resource目录需要，是serverRoot目录，里头包含ip资源库等资源
.env 配置文件，优先级最高 (可选)

部署&编译流程：

创建并导入数据库文件 latest.sql
修改数据库连接配置，在.env文件或者mainifeast/config/config.yaml 修改,
下载项目文件
go mod tidy 下载并清理依赖
go build main.go 或者 gf build main.go -n main -a amd64 -s linux -p .
运行

由于是以工具库方式提供服务，需要进行引用运行。
根据example目录下的示例文件进行适配引用。项目被引用运行时，是可以实现调试目的。
相关引用参考 example/main.go internal/boot/boot.go

项目脚手架make命令:

make dao: 根据“hack”文件夹中的配置文件为“entity/dao/do”生成go文件，具体生成的模型目标文件夹需要在Makefile文件标明。
make service: 解析“逻辑”文件夹生成service服务接口。具体生成的service服务接口目标文件夹需要在Makefile文件标明。

不推荐直接在本项目使用 gf gen 等命令，将会导致文件生成的位置不在预期位置，如果一定要用先了解相关参数后再用。

项目脚手架gf命令：

gf version：查看框架版本
gf init projectName : 用于创建gofream框架结构项目
gf build ... ：编译项目
gf run main.go ：运行
gf gen dao：根据hack中的配置文件，生成模型文件，如果配置了make脚手架，不建议直接使用该命令生成。
gf gen service：生成服务接口，如果配置了make脚手架，不建议直接使用该命令生成。
gf [COMMAND] -h: 查看命令帮助说明

四、代码风格规范

代码风格并不影响程序的运行，也不会给你的程序带来潜在的危险。但一段好的代码风格，能让人阅读起来特别舒服，特别是阅读别人代码的时候。

代码风格规范

1、包名

统一使用小写，用下划线作为分隔符，以自然语义缩写或全称作为分隔

2、类名

由于golang属于面向过程编程，没有真正意义上的类。
本项目将逻辑封装成服务对象、控制器对象等，通过封装后的对象进行关业务调用，以实现仿类操作效果，这里称作“伪类”。那么伪类的定义规范如下：

伪类采用大驼峰的命名形式，所谓大驼峰就是首字母大写，例如UpperCameCase

3、常量

全局常量：遵行类名的命名一样的方式。
局部常量：局部常量则采用小驼峰的形式。所谓局部常量指的是方法/内/包内的常量。

4、大括号代码域

遵循JAVA风格，缩进直接紧接后面括号，例如：

int Foo(bool isBar) {
    if (isBar) {
        bar();
        return 1;
    }
    return 0
}

5、tab缩进

每个tab缩进，用4个空格代替。

接口风格规范

为了能更好的同步接口相关约束，规范接口文档的自动生成、并支持接口的相关参数自动校验项目接口做如下规范定义。

接口规范

1、所有逻辑接口需要封装成控制器对象，统一保存在controller文件夹下
2、一个控制器接口方法首字母大写的驼峰命名方式
3、每个接口方法只能包含2个参数，分别为接口上下文对象 Context 和请求参数定义（以Req结尾的类型参数定义）。接口方法返回值只能有2个固定返回值，第一个是要返回的数据，第二个是错误异常信息。
例如：

func (a *cAuth) Login(ctx context.Context, req *sysapi.LoginReq) (res *sysapi.LoginRes, err error) {
    return nil, nil
}

方法参数：ctx context.Context 为请求上下文，不需要用到上下文时，变量 ctx 可用下划线代替
方法参数：req *sys_api.LoginReq 为请求参数定义，必须以Req结尾，且必须是指针对象，不需要用到前端请求参数时，变量 req 可用下划线代替
方法返回：*sys_api.LoginRes 为方法第一个返回参数，且必须以Res结尾，返回值的变量名称为可选，如：(*sys_api.LoginRes,error)
方法返回：err error 为方法第二个返回参数，必填项，该参数类型固定且不可修改

请求参数规范

请求参数的定义统一在对象成员属性中实现约束、描述、验证规则等相关定义，例如：

type LoginReq struct {
    g.Meta `path:"/login" method:"post" summary:"登录" tags:"鉴权"`
	Username string `json:"username" v:"required#请输入用户名" dc:"登录账号"`
	Password string `json:"password" v:"required#请输入密码" dc:"登录密码"`
    Captcha  string `json:"captcha" v:"required#请输入验证吗" dc:"验证码"`
}

LoginReq 作为请求对象的类型名称，必须以首字母大写，且以Res结尾
g.Meta path:定义请求路径，method:定义请求类型,summary:定义接口概要说明，tags:定义接口在文档生成上的分类
请求参数属性：Username，Password，Captcha，定义了请求参数的细则，包括但不限于json:说明参数格式，v:参数校验规则和校验失败后的提示信息,dc:参数描述

五、Git Commit 语义化规范

作用：

能加快 Code Review 的流程
根据 Git Commit 的元数据生成 Changelog
后续维护者可以知道 Feature 被修改的原因
统一团队 Git Commit 日志标准，便于后续代码 Review 和版本发布
main、dev两个分支提交类型限定为：feat,fix,docs,style,refactor,perf,test,chore,revert等
提交格式参考：

<type>(<scope>):<subject>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>

Type 代表了某次提交的类型，比如是修复一个 bug 还是增加了一个新的 feature。常用类型如下：
- feat：新增 feature
- fix：修复 bug
- docs：仅仅修改了文档，比如 README、CHANGELOG 等等
- style：仅仅修改了空格、格式缩进、多行等等，不改变逻辑
- refactor：代码重构，没有加新的功能或者修复 bug
- perf：优化相关，比如提升性能、体验等
- test：测试用例，包括单元测试、集成测试等
- chore：改变构建流程，或者增加依赖库、工具等
- revert：回滚到上一个版本
Scope 字段用于说明本次 commit 所影响的范围，比如视图层、数据模型或者路由模块等，是一个可选参数。
Subject 字段是本次 commit 的一个概要，需要用最简洁的语言来说明本次修改的内容。
Body 可以使用多行文本详细地说明本次提交所改动的一些细节，从而帮助后续的使用者们更好地了解代码的内容。
Footer 大部分只用于两种情况
- 不兼容变动
  - 如果本次的 commit 与前一个版本的代码无法兼容，那么 Footer 部分需要以 BREAKING CHANGE 开头，后面描述本次变动的详细情况以及迁移到新版本代码的方法。
- 关闭 Issue
  - 如果当前 commit 针对某个 issue，那么可以在 Footer 部分关闭这个 issue 。以 Close 开头，后面用 # 号标识对应的 Issue 号码。

Commitizen

如果觉得自己写规范的 comment 信息太麻烦，那么可以使用Commitizen ，可以辅助撰写一个合格的 Commit message 工具。

注意事项

项目规范

项目规范：
- 所有项目包名统一规范用小写，下划线隔开

- 包名不支持横杠,项目名支持横杠，包名不支持

项目引入问题：
- 项目引入是有先后顺序区分的。

方法命名规范

方法命名规范: 
Get 前缀代表获取单一记录数据
Query 代表返回列表数据，需要包含分页信息
Update 代表更新数据信息
Delete 代表删除数据
Set 代表设置相关状态或类型

注意：Query 前缀返回的数据结构必须是 CollectRes

接口规范

不要缩写  例如： addr  u_id 

使用驼峰命名，不要使用短下划线_   例如：order_by --> orderBy    user_id  --> userId

参数使用规范

  字段名不要使用硬编码，如果数据库改动了，那么重新生成的文件不会自动适配。

  OperatorEmployee.Columns().Id 这种方式

# Packages

# README

Weixin

一、技术选型

开发工具

语言/框架/类库

数据库

脚本工具

二、项目结构

weixin-library 理解为这是一个SDK库，项目大部分实现是基于第三方应用代商家发起Api调用

三、项目编译/运行

前言：

部署&编译流程：

项目脚手架make命令:

项目脚手架gf命令：

四、代码风格规范

代码风格规范

1、包名

2、类名

3、常量

4、大括号代码域

5、tab缩进

接口风格规范

接口规范

请求参数规范

五、Git Commit 语义化规范

作用：

Commitizen

注意事项

项目规范

方法命名规范

接口规范

参数使用规范