1.orm新增调用方法,2.api response新增调用方法并标记部分方法为弃用状态,3.更新README_EN,4.更新examples

README_EN.md

@@ -8,7 +8,7 @@ English | [简体中文](./README.md)
 
 ## Whats the go-sail？
 
-**go-sail** is a lightweight progressive web framework implemented using Go language. It is not the product of reinventing the wheel, but stands on the shoulders of giants and integrates existing excellent components to help users build stable and reliable services in the simplest way.
+**go-sail** is a lightweight progressive web framework implemented using Go language. **It is not the product of reinventing the wheel**, but stands on the shoulders of giants and integrates existing excellent components to help users build stable and reliable services in the simplest way.
 As its name suggests, you can regard it as the beginning of your own journey in the golang ecosystem. go-sail will help you start lightly and set sail.
 
 ## How to use
@@ -53,7 +53,8 @@ Console screenshot after launched like this:
 
 ## Features
 - Get components
-> go-sail启动时，会根据配置文件启动相应的应用组件，可使用`sail`关键字统一获取
+> When go-sail is started, the corresponding application components will be started according to the configuration file, 
+> which can be obtained uniformly using the `sail` keyword.
 ```go
 import (
     "github.com/keepchen/go-sail/v3/sail"

examples/pkg/app/user/service/sayhello.go

@@ -35,6 +35,7 @@ func SayHelloSvc(c *gin.Context) {
 
 	resp.Data = fmt.Sprintf("hello, %s", nickname)
 
-	sail.Response(c).Assemble(constants.ErrNone, resp).Send()
+	sail.Response(c).Builder(constants.ErrNone, resp).Send()
+	//sail.Response(c).Assemble(constants.ErrNone, resp).Send()
 	//sail.Response(c).Data(resp.Data)
 }

http/api/response.go

@@ -13,11 +13,13 @@ import (
 // Responder 响应器
 type Responder interface {
 	// Builder 组装返回数据
-	//
-	// Assemble 方法的语法糖
 	Builder(code constants.ICodeType, resp dto.IResponse, message ...string) Responder
 	// Assemble 组装返回数据
 	//
+	// Deprecated: Assemble is deprecated,it will be removed in the future.
+	//
+	// Please use Builder instead.
+	//
 	// 该方法会根据传递的code码自动设置http状态、描述信息、当前系统毫秒时间戳以及请求id(需要在路由配置中调用 middleware.LogTrace 中间件)
 	Assemble(code constants.ICodeType, resp dto.IResponse, message ...string) Responder
 	// Status 指定http状态码
@@ -28,8 +30,18 @@ type Responder interface {
 	SendWithCode(httpCode int)
 	// Send 响应请求
 	Send()
+	// Wrap 组装返回数据
+	//
+	//该方法与 Builder 的区别在于data参数不需要实现 dto.IResponse 接口
+	//
+	// 该方法会根据传递的code码自动设置http状态、描述信息、当前系统毫秒时间戳以及请求id(需要在路由配置中调用 middleware.LogTrace 中间件)
+	Wrap(code constants.ICodeType, data interface{}, message ...string) Responder
 	// SimpleAssemble 组装返回数据(轻量版)
 	//
+	// Deprecated: SimpleAssemble is deprecated,it will be removed in the future.
+	//
+	// Please use Wrap instead.
+	//
 	// 该方法会根据传递的code码自动设置http状态、描述信息、当前系统毫秒时间戳以及请求id(需要在路由配置中调用 middleware.LogTrace 中间件)
 	SimpleAssemble(code constants.ICodeType, data interface{}, message ...string) Responder
 	// Data 返回数据
@@ -115,7 +127,7 @@ func Response(c *gin.Context) Responder {
 //
 // Assemble 方法的语法糖
 func (a *responseEngine) Builder(code constants.ICodeType, resp dto.IResponse, message ...string) Responder {
-	return a.Assemble(code, resp, message...)
+	return a.mergeBody(code, resp, message...)
 }
 
 // Success 返回成功
@@ -149,7 +161,7 @@ func (a *responseEngine) Failure(message ...string) {
 //
 // 2.业务码为code
 func (a *responseEngine) Failure200(code constants.ICodeType, message ...string) {
-	a.SimpleAssemble(code, nil, message...).SendWithCode(http.StatusOK)
+	a.Wrap(code, nil, message...).SendWithCode(http.StatusOK)
 }
 
 // Failure400 返回失败
@@ -160,7 +172,7 @@ func (a *responseEngine) Failure200(code constants.ICodeType, message ...string)
 //
 // 2.业务码为code
 func (a *responseEngine) Failure400(code constants.ICodeType, message ...string) {
-	a.SimpleAssemble(code, nil, message...).SendWithCode(http.StatusBadRequest)
+	a.Wrap(code, nil, message...).SendWithCode(http.StatusBadRequest)
 }
 
 // Failure500 返回失败
@@ -171,7 +183,7 @@ func (a *responseEngine) Failure400(code constants.ICodeType, message ...string)
 //
 // 2.业务码为code
 func (a *responseEngine) Failure500(code constants.ICodeType, message ...string) {
-	a.SimpleAssemble(code, nil, message...).SendWithCode(http.StatusInternalServerError)
+	a.Wrap(code, nil, message...).SendWithCode(http.StatusInternalServerError)
 }
 
 // Data 返回数据
@@ -190,18 +202,35 @@ func (a *responseEngine) Data(data interface{}) {
 		code = constants.ErrNone
 	}
 
-	a.SimpleAssemble(code, data).Send()
+	a.Wrap(code, data).Send()
+}
+
+// Wrap 组装返回数据(轻量版)
+//
+// 该方法与 Builder 的区别在于data参数不需要实现 dto.IResponse 接口
+//
+// 该方法会根据传递的code码自动设置http状态、描述信息、当前系统毫秒时间戳以及请求id(需要在路由配置中调用 middleware.LogTrace 中间件)
+func (a *responseEngine) Wrap(code constants.ICodeType, data interface{}, message ...string) Responder {
+	return a.mergeBody(code, data, message...)
 }
 
 // SimpleAssemble 组装返回数据(轻量版)
 //
+// Deprecated: SimpleAssemble is deprecated,it will be removed in the future.
+//
+// Please use Wrap instead.
+//
 // 该方法会根据传递的code码自动设置http状态、描述信息、当前系统毫秒时间戳以及请求id(需要在路由配置中调用 middleware.LogTrace 中间件)
 func (a *responseEngine) SimpleAssemble(code constants.ICodeType, data interface{}, message ...string) Responder {
 	return a.mergeBody(code, data, message...)
 }
 
 // Assemble 组装返回数据
 //
+// Deprecated: Assemble is deprecated,it will be removed in the future.
+//
+// Please use Builder instead.
+//
 // 该方法会根据传递的code码自动设置http状态、描述信息、当前系统毫秒时间戳以及请求id(需要在路由配置中调用 middleware.LogTrace 中间件)
 func (a *responseEngine) Assemble(code constants.ICodeType, resp dto.IResponse, message ...string) Responder {
 	return a.mergeBody(code, resp, message...)

orm/svc.go

@@ -11,8 +11,8 @@
 package orm
 
 import (
+	"context"
 	"database/sql"
-	"errors"
 
 	"github.com/keepchen/go-sail/v3/lib/logger"
 	"go.uber.org/zap"
@@ -33,6 +33,8 @@ type Svc interface {
 	Limit(limit int) Svc
 	Having(query interface{}, args ...interface{}) Svc
 	Scopes(fns ...func(*gorm.DB) *gorm.DB) Svc
+	Session(session *gorm.Session) Svc
+	WithContext(ctx context.Context) Svc
 
 	Create(value interface{}) error
 	Find(dest interface{}, conditions ...interface{}) error
@@ -43,6 +45,9 @@ type Svc interface {
 	Delete(value interface{}, conditions ...interface{}) error
 	Transaction(fc func(tx *gorm.DB) error, opts ...*sql.TxOptions) (err error)
 
+	//Unwrap 返回gorm原生实例
+	Unwrap() *gorm.DB
+
 	//R 使用读实例
 	R() Svc
 	//W 使用写实例
@@ -216,6 +221,34 @@ func (a *SvcImpl) Scopes(fns ...func(*gorm.DB) *gorm.DB) Svc {
 	return a
 }
 
+func (a *SvcImpl) Session(session *gorm.Session) Svc {
+	if a.tx == nil {
+		a.tx = a.dbw
+	}
+
+	a.tx = a.tx.Session(session)
+
+	return a
+}
+
+func (a *SvcImpl) WithContext(ctx context.Context) Svc {
+	if a.tx == nil {
+		a.tx = a.dbw
+	}
+
+	a.tx = a.tx.WithContext(ctx)
+
+	return a
+}
+
+func (a *SvcImpl) Unwrap() *gorm.DB {
+	if a.tx == nil {
+		a.tx = a.dbw
+	}
+
+	return a.tx
+}
+
 func (a *SvcImpl) Create(value interface{}) error {
 	err := a.dbw.Create(value).Error
 
@@ -233,9 +266,9 @@ func (a *SvcImpl) Find(dest interface{}, conditions ...interface{}) error {
 		a.tx = a.dbw
 	}
 
-	err := a.tx.Find(dest, conditions...).Error
+	err := IgnoreErrRecordNotFound(a.tx.Find(dest, conditions...))
 
-	if err != nil && !errors.Is(err, gorm.ErrRecordNotFound) {
+	if err != nil {
 		a.logger.Error("[Database service]:Find:Error",
 			zap.String("value", logger.MarshalInterfaceValue(dest)),
 			zap.String("conditions", logger.MarshalInterfaceValue(conditions)),
@@ -252,8 +285,8 @@ func (a *SvcImpl) FindOrNil(dest interface{}, conditions ...interface{}) error {
 
 	err := IgnoreErrRecordNotFound(a.tx.Find(dest, conditions...))
 
-	if err != nil && !errors.Is(err, gorm.ErrRecordNotFound) {
-		a.logger.Error("[Database service]:Find:Error",
+	if err != nil {
+		a.logger.Error("[Database service]:FindOrNil:Error",
 			zap.String("value", logger.MarshalInterfaceValue(dest)),
 			zap.String("conditions", logger.MarshalInterfaceValue(conditions)),
 			zap.Errors("errors", []error{err}))
@@ -267,9 +300,9 @@ func (a *SvcImpl) First(dest interface{}, conditions ...interface{}) error {
 		a.tx = a.dbw
 	}
 
-	err := a.tx.First(dest, conditions...).Error
+	err := IgnoreErrRecordNotFound(a.tx.First(dest, conditions...))
 
-	if err != nil && !errors.Is(err, gorm.ErrRecordNotFound) {
+	if err != nil {
 		a.logger.Error("[Database service]:First:Error",
 			zap.String("value", logger.MarshalInterfaceValue(dest)),
 			zap.String("conditions", logger.MarshalInterfaceValue(conditions)),
@@ -286,8 +319,8 @@ func (a *SvcImpl) FirstOrNil(dest interface{}, conditions ...interface{}) error
 
 	err := IgnoreErrRecordNotFound(a.tx.First(dest, conditions...))
 
-	if err != nil && !errors.Is(err, gorm.ErrRecordNotFound) {
-		a.logger.Error("[Database service]:First:Error",
+	if err != nil {
+		a.logger.Error("[Database service]:FirstOrNil:Error",
 			zap.String("value", logger.MarshalInterfaceValue(dest)),
 			zap.String("conditions", logger.MarshalInterfaceValue(conditions)),
 			zap.Errors("errors", []error{err}))
@@ -382,9 +415,9 @@ func (a *SvcImpl) Paginate(dest interface{}, page, pageSize int) (int64, error)
 	var total int64
 	a.tx.Count(&total)
 
-	err := a.tx.Scopes(Paginate(page, pageSize)).Find(dest).Error
+	err := IgnoreErrRecordNotFound(a.tx.Scopes(Paginate(page, pageSize)).Find(dest))
 
-	if err != nil && !errors.Is(err, gorm.ErrRecordNotFound) {
+	if err != nil {
 		a.logger.Error("[Database service]:Paginate:Error",
 			zap.String("value", logger.MarshalInterfaceValue(dest)),
 			zap.Errors("errors", []error{err}))

sail/components.go

@@ -79,7 +79,7 @@ func GetLogger(module ...string) *zap.Logger {
 
 // Response http响应组件
 func Response(c *gin.Context) api.Responder {
-	return api.New(c)
+	return api.Response(c)
 }
 
 // GetKafkaInstance 获取kafka完整实例