From 93d49c61a177a883cbf69874d94850e340b60f4c Mon Sep 17 00:00:00 2001 From: yinheli Date: Tue, 13 Jul 2021 10:47:39 +0800 Subject: [PATCH] update core document --- core/const.go | 21 +++++++++++---------- core/middleware/pprof.go | 1 + core/middleware/prometheus.go | 1 + core/middleware/trace.go | 1 + core/xservice/client.go | 3 +++ core/xservice/option.go | 13 +++++++++++++ core/xservice/server.go | 9 +++++++++ core/xservice/xservice.go | 7 +++++++ 8 files changed, 46 insertions(+), 10 deletions(-) diff --git a/core/const.go b/core/const.go index aa85064..0ecbabe 100644 --- a/core/const.go +++ b/core/const.go @@ -1,24 +1,25 @@ package core +// ContextKey for context key, string alias type ContextKey string const ( // context ContextHeaderXRequestID ContextKey = "X-Request-ID" // requestId key - DefaultServiceName = "xservice-default" + DefaultServiceName = "xservice-default" // default service name // env key - EnvServiceName = "XSERVICE_NAME" - EnvServiceVersion = "XSERVICE_VERSION" - EnvEtcd = "XSERVICE_ETCD" - EnvEtcdUser = "XSERVICE_ETCD_USER" - EnvEtcdPassword = "XSERVICE_ETCD_PASSWORD" + EnvServiceName = "XSERVICE_NAME" // serviceName key + EnvServiceVersion = "XSERVICE_VERSION" // serviceVersion key + EnvEtcd = "XSERVICE_ETCD" // etc endpoint key + EnvEtcdUser = "XSERVICE_ETCD_USER" // etcdUser key + EnvEtcdPassword = "XSERVICE_ETCD_PASSWORD" // etcdPassword key // config key - ConfigServiceAddr = "http.address" - ConfigServiceAdvertisedAddr = "http.advertised_address" + ConfigServiceAddr = "http.address" // config http address key + ConfigServiceAdvertisedAddr = "http.advertised_address" // config http advertise address key - ServiceConfigKeyPrefix = "xservice/config" - ServiceRegisterKeyPrefix = "xservice/register" + ServiceConfigKeyPrefix = "xservice/config" // service config key prefix + ServiceRegisterKeyPrefix = "xservice/register" // service register key prefix ) diff --git a/core/middleware/pprof.go b/core/middleware/pprof.go index 360ab30..41e27a5 100644 --- a/core/middleware/pprof.go +++ b/core/middleware/pprof.go @@ -7,6 +7,7 @@ import ( "github.com/labstack/echo/v4" ) +// Pprof is pprof middleware func Pprof() echo.MiddlewareFunc { return echo.WrapMiddleware(func(handler http.Handler) http.Handler { return http.DefaultServeMux diff --git a/core/middleware/prometheus.go b/core/middleware/prometheus.go index 4e0615b..3d2f776 100644 --- a/core/middleware/prometheus.go +++ b/core/middleware/prometheus.go @@ -9,6 +9,7 @@ import ( "github.com/prometheus/client_golang/prometheus/promauto" ) +// Prometheus is prometheus middleware func Prometheus(namespace, subsystem string) echo.MiddlewareFunc { requests := promauto.NewCounterVec(prometheus.CounterOpts{ Namespace: namespace, diff --git a/core/middleware/trace.go b/core/middleware/trace.go index f7ea132..06787b0 100644 --- a/core/middleware/trace.go +++ b/core/middleware/trace.go @@ -7,6 +7,7 @@ import ( "github.com/opentracing/opentracing-go" ) +// Trace is opentracing middleware func Trace(bodyDump bool, skipper middleware.Skipper) echo.MiddlewareFunc { return jaegertracing.TraceWithConfig(jaegertracing.TraceConfig{ Tracer: opentracing.GlobalTracer(), diff --git a/core/xservice/client.go b/core/xservice/client.go index 9e874ac..d9085e6 100644 --- a/core/xservice/client.go +++ b/core/xservice/client.go @@ -14,7 +14,9 @@ import ( "github.com/xinpianchang/xservice/pkg/log" ) +// Client is the client for xservice type Client interface { + // GrpcClientConn returns a grpc client connection GrpcClientConn(ctx context.Context, service string, desc *grpc.ServiceDesc, endpoint ...string) (*grpc.ClientConn, error) } @@ -39,6 +41,7 @@ func newClient(opts *Options) Client { return client } +// GrpcClientConn returns a grpc client connection func (t *clientImpl) GrpcClientConn(ctx context.Context, service string, desc *grpc.ServiceDesc, endpoint ...string) (*grpc.ClientConn, error) { if len(endpoint) > 0 { return grpc.DialContext(ctx, endpoint[0], grpc.WithInsecure()) diff --git a/core/xservice/option.go b/core/xservice/option.go index 27b6e0d..a9efca0 100644 --- a/core/xservice/option.go +++ b/core/xservice/option.go @@ -19,6 +19,7 @@ import ( "github.com/xinpianchang/xservice/pkg/netx" ) +// Options for xservice core option type Options struct { Name string Version string @@ -30,50 +31,62 @@ type Options struct { EchoTracingSkipper middleware.Skipper } +// Option for option config type Option func(*Options) +// Name set service name func Name(name string) Option { return func(o *Options) { o.Name = name } } +// Version set service version func Version(version string) Option { return func(o *Options) { o.Version = version } } +// Build set build version for service func Build(build string) Option { return func(o *Options) { o.Build = build } } +// Description set description for service func Description(description string) Option { return func(o *Options) { o.Description = description } } +// Config set custom viper instance for xservice configuration +// +// Note: default configuration enabled watch feature, if set custom viper, +// watch feature should implements by you self func Config(config *viper.Viper) Option { return func(o *Options) { o.Config = config } } +// WithGrpcOptions add additional grpc server option func WithGrpcOptions(options ...grpc.ServerOption) Option { return func(o *Options) { o.GrpcOptions = options } } +// WithSentry set sentry option for enable sentry func WithSentry(options sentry.ClientOptions) Option { return func(o *Options) { o.SentryOptions = options } } +// WithEchoTracingSkipper set tracing skipper func WithEchoTracingSkipper(skipper middleware.Skipper) Option { return func(o *Options) { o.EchoTracingSkipper = skipper diff --git a/core/xservice/server.go b/core/xservice/server.go index f9667d9..7059346 100644 --- a/core/xservice/server.go +++ b/core/xservice/server.go @@ -40,9 +40,15 @@ import ( "github.com/xinpianchang/xservice/pkg/tracingx" ) +// Server is the interface for xservice server type Server interface { + // Echo returns the echo instance Echo() *echo.Echo + + // Serve start and listen server Serve() error + + // GrpcRegister registers a gRPC service GrpcRegister(desc *grpc.ServiceDesc, impl interface{}, handler ...GrpcRegisterHandler) } @@ -52,6 +58,7 @@ type grpcService struct { Handler GrpcRegisterHandler } +// GrpcRegisterHandler is the interface for gRPC service register handler type GrpcRegisterHandler func(ctx context.Context, mux *gwrt.ServeMux, conn *grpc.ClientConn) error type serverImpl struct { @@ -79,6 +86,7 @@ func (t *serverImpl) Echo() *echo.Echo { return t.echo } +// Serve starts and listen server func (t *serverImpl) Serve() error { address := t.getHttpAddress() @@ -158,6 +166,7 @@ func (t *serverImpl) Serve() error { return nil } +// GrpcRegister registers a gRPC service func (t *serverImpl) GrpcRegister(desc *grpc.ServiceDesc, impl interface{}, hs ...GrpcRegisterHandler) { var handler GrpcRegisterHandler if len(hs) > 0 { diff --git a/core/xservice/xservice.go b/core/xservice/xservice.go index be12b81..a47a162 100644 --- a/core/xservice/xservice.go +++ b/core/xservice/xservice.go @@ -15,6 +15,7 @@ import ( "github.com/xinpianchang/xservice/pkg/tracingx" ) +// Service is a service interface, core api for xservice type Service interface { Name() string Options() *Options @@ -29,6 +30,7 @@ type serviceImpl struct { server Server } +// New create new xservice instance func New(options ...Option) Service { opts := loadOptions(options...) @@ -40,22 +42,27 @@ func New(options ...Option) Service { return service } +// Name get service name func (t *serviceImpl) Name() string { return t.options.Name } +// Options get service options func (t *serviceImpl) Options() *Options { return t.options } +// Client get service client func (t *serviceImpl) Client() Client { return t.client } +// Server get service server func (t *serviceImpl) Server() Server { return t.server } +// String get service formatted name func (t *serviceImpl) String() string { return fmt.Sprint(t.Name(), "/", t.options.Version, " - ", t.options.Description) }