pingkratos

pingkratos

Simple and fast Ping service package to support the Kratos framework, with both gRPC and HTTP protocols.

CHINESE README

中文说明

Features

✅ Simple Design: Clean and straightforward service structure ✅ Dual-Protocol Support: Supports both gRPC and HTTP protocols ✅ Native Integration: Seamless integration with the Kratos framework ✅ Built-in Tests: Comprehensive test coverage included ✅ Modern Schema: Uses Protocol Buffers to define services ✅ Zero Config: Out-of-the-box Ping service implementation

Installation

go get github.com/orzkratos/pingkratos

Usage

HTTP Example

package main

import (
	"time"

	"github.com/go-kratos/kratos/v2"
	"github.com/go-kratos/kratos/v2/middleware/logging"
	"github.com/go-kratos/kratos/v2/middleware/recovery"
	"github.com/go-kratos/kratos/v2/transport/http"
	"github.com/orzkratos/pingkratos/clientpingkratos"
	"github.com/orzkratos/pingkratos/serverpingkratos"
	"github.com/orzkratos/zapkratos"
	"github.com/yyle88/must"
	"github.com/yyle88/rese"
	"github.com/yyle88/zaplog"
	"go.uber.org/zap"
)

func main() {
	// Setup logging to show ping request logs
	zapKratos := zapkratos.NewZapKratos(zaplog.LOGGER, zapkratos.NewOptions())

	// Setup HTTP service on port 8000
	httpSrv := http.NewServer(
		http.Address(":8000"),
		http.Middleware(
			recovery.Recovery(),
			logging.Server(zapKratos.GetLogger("HTTP")),
		),
		http.Timeout(time.Minute),
	)

	// Setup ping service
	pingService := serverpingkratos.NewPingService(zapKratos.GetLogger("PING"))
	clientpingkratos.RegisterPingHTTPServer(httpSrv, pingService)

	// Setup and start application
	app := kratos.New(
		kratos.Name("pingkratos-http-demo"),
		kratos.Server(httpSrv),
	)

	zaplog.LOG.Info("Starting HTTP Ping service", zap.String("address", ":8000"))

	// Run application (awaiting shutdown)
	must.Done(app.Run())
	defer rese.F0(app.Stop)
}

⬆️ Source: Source

gRPC Example

package main

import (
	"time"

	"github.com/go-kratos/kratos/v2"
	"github.com/go-kratos/kratos/v2/middleware/logging"
	"github.com/go-kratos/kratos/v2/middleware/recovery"
	"github.com/go-kratos/kratos/v2/transport/grpc"
	"github.com/orzkratos/pingkratos/clientpingkratos"
	"github.com/orzkratos/pingkratos/serverpingkratos"
	"github.com/orzkratos/zapkratos"
	"github.com/yyle88/must"
	"github.com/yyle88/rese"
	"github.com/yyle88/zaplog"
	"go.uber.org/zap"
)

func main() {
	// Setup logging to show ping request logs
	zapKratos := zapkratos.NewZapKratos(zaplog.LOGGER, zapkratos.NewOptions())

	// Setup gRPC service on port 9000
	grpcSrv := grpc.NewServer(
		grpc.Address(":9000"),
		grpc.Middleware(
			recovery.Recovery(),
			logging.Server(zapKratos.GetLogger("GRPC")),
		),
		grpc.Timeout(time.Minute),
	)

	// Setup ping service
	pingService := serverpingkratos.NewPingService(zapKratos.GetLogger("PING"))
	clientpingkratos.RegisterPingServer(grpcSrv, pingService)

	// Setup and start application
	app := kratos.New(
		kratos.Name("pingkratos-grpc-demo"),
		kratos.Server(grpcSrv),
	)

	zaplog.LOG.Info("Starting gRPC Ping service", zap.String("address", ":9000"))

	// Run application (awaiting shutdown)
	must.Done(app.Run())
	defer rese.F0(app.Stop)
}

⬆️ Source: Source

Dependencies

Core Dependencies

• github.com/go-kratos/kratos/v2 - Kratos framework
• google.golang.org/grpc - gRPC support
• google.golang.org/protobuf - Protocol Buffers
• github.com/yyle88/* - Utilities

Examples

Integration with Kratos Project

To integrate pingkratos into the Kratos project, follow these steps:

1. Add Dependency

go get github.com/orzkratos/pingkratos

2. Setup Wire Provider

In internal/service/service.go:

import (
    "github.com/google/wire"
    "github.com/orzkratos/pingkratos/serverpingkratos"
)

var ProviderSet = wire.NewSet(
    NewGreeterService,
    serverpingkratos.NewPingService,
)

3. Setup HTTP Endpoint

In internal/server/http.go:

import (
    "github.com/orzkratos/pingkratos/clientpingkratos"
    "github.com/orzkratos/pingkratos/serverpingkratos"
)

func NewHTTPServer(
    c *conf.Server,
    greeter *service.GreeterService,
    pingService *serverpingkratos.PingService,
    logger log.Logger,
) *http.Server {
    srv := http.NewServer(opts...)
    v1.RegisterGreeterHTTPServer(srv, greeter)
    clientpingkratos.RegisterPingHTTPServer(srv, pingService)
    return srv
}

4. Setup gRPC Endpoint

In internal/server/grpc.go:

import (
    "github.com/orzkratos/pingkratos/clientpingkratos"
    "github.com/orzkratos/pingkratos/serverpingkratos"
)

func NewGRPCServer(
    c *conf.Server,
    greeter *service.GreeterService,
    pingService *serverpingkratos.PingService,
    logger log.Logger,
) *grpc.Server {
    srv := grpc.NewServer(opts...)
    v1.RegisterGreeterServer(srv, greeter)
    clientpingkratos.RegisterPingServer(srv, pingService)
    return srv
}

5. Generate Wire Code

wire ./cmd/demo-app/...

Demo Projects

Complete working examples:

• pingkratos-demos - Complete Kratos project integration

Unit test examples: TEST.

📄 License

MIT License. See LICENSE.

🤝 Contributing

Contributions are welcome! Report bugs, suggest features, and contribute code:

• 🐛 Found a mistake? Open an issue on GitHub with reproduction steps
• 💡 Have a feature idea? Create an issue to discuss the suggestion
• 📖 Documentation confusing? Report it so we can improve
• 🚀 Need new features? Share the use cases to help us understand requirements
• ⚡ Performance issue? Help us optimize through reporting slow operations
• 🔧 Configuration problem? Ask questions about complex setups
• 📢 Follow project progress? Watch the repo to get new releases and features
• 🌟 Success stories? Share how this package improved the workflow
• 💬 Feedback? We welcome suggestions and comments

🔧 Development

New code contributions, follow this process:

1. Fork: Fork the repo on GitHub (using the webpage UI).
2. Clone: Clone the forked project (git clone https://github.com/yourname/repo-name.git).
3. Navigate: Navigate to the cloned project (cd repo-name)
4. Branch: Create a feature branch (git checkout -b feature/xxx).
5. Code: Implement the changes with comprehensive tests
6. Testing: (Golang project) Ensure tests pass (go test ./...) and follow Go code style conventions
7. Documentation: Update documentation to support client-facing changes and use significant commit messages
8. Stage: Stage changes (git add .)
9. Commit: Commit changes (git commit -m "Add feature xxx") ensuring backward compatible code
10. Push: Push to the branch (git push origin feature/xxx).
11. PR: Open a merge request on GitHub (on the GitHub webpage) with detailed description.

Please ensure tests pass and include relevant documentation updates.

🌟 Support

Welcome to contribute to this project via submitting merge requests and reporting issues.

Project Support:

• ⭐ Give GitHub stars if this project helps you
• 🤝 Share with teammates and (golang) programming friends
• 📝 Write tech blogs about development tools and workflows - we provide content writing support
• 🌟 Join the ecosystem - committed to supporting open source and the (golang) development scene

Have Fun Coding with this package! 🎉🎉🎉

GitHub Stars