gonectr

README

English  ｜  中文

gonectr

• gonectr
  • Introduction
  • Installation
    • Method 1: Using go install (Recommended)
    • Method 2: Direct Binary Download
  • Feature Overview
  • Detailed Usage Guide
    • 1. create Command: Create Gone Projects from Templates
      • View Help:
      • Basic Usage: Create Project
      • Create Project with Specific Template
      • List All Available Templates
      • Create Project with Module Name
      • Create Project from Remote Git Repository Template
    • 2. install Command: Install Gone Modules and Generate module.load.go
      • View Help:
      • Basic Usage: Install Module
      • Specify LoadFunc
      • Real Example
      • Uninstall/Modify Module
    • gone-io Official Modules, Supporting Short Names
    • 3. generate Command: Generate *.gone.go Files for Gone Projects
      • Functionality
      • Specify Scan Directory
      • Specify Main Function Directory
      • Advanced Usage: Generate import.gone.go for Non-main Package
      • Advanced Usage: Support Multiple Gone Instances
      • Use with go generate
    • 4. mock Command: Generate Mock Code
      • View Help:
      • Basic Usage
      • More Options
    • 5. build Command: Build Gone Projects
      • Features
      • View Help:
      • Basic Usage
    • 6. run Command: Run Gone Projects
      • Features
      • View Help:
      • Basic Usage
  • FAQ
    • Q: What is the relationship between gonectr and standard Go tools?
    • Q: How to upgrade gonectr to the latest version?
    • Q: Should *.gone.go files be included in version control?
  • More Resources

Command-line tool for Gone framework, simplifying project creation, module management, and code generation

Introduction

gonectr is the official command-line tool for the Gone framework, designed to streamline the development process of Gone projects. It provides a series of convenient commands to help developers quickly create projects, manage modules, generate code, and build applications. Whether you're new to Gone or an experienced developer, gonectr can significantly improve your development efficiency.

Installation

Method 1: Using go install (Recommended)

Run the following command to install gonectr:

go install github.com/gone-io/gonectr@latest

After installation, gonectr will be located in the $GOPATH/bin directory. Make sure this directory is added to your system's $PATH environment variable for global access to the gonectr command.

Tip: If you're unsure about the location of $GOPATH, you can check it by running go env GOPATH.

Method 2: Direct Binary Download

You can also visit the gonectr/releases page to download the latest version binary for your operating system, then:

1. Extract the downloaded file
2. Copy the extracted gonectr executable to a directory in your system PATH
3. Ensure the file has execution permissions (on Linux/macOS, you may need to run chmod +x gonectr)

Feature Overview

gonectr provides the following core features:

• Project Creation: Quickly scaffold Gone project architecture from templates
• Module Installation: Integrate Gone modules and automatically generate loading code
• Code Generation: Automatically generate necessary Gone framework integration code
• Mock Generation: Create Mock implementations for interfaces, facilitating unit testing
• Build and Run: Simplify project building and running processes

Detailed Usage Guide

1. create Command: Create Gone Projects from Templates

The create command helps you quickly create Gone projects based on preset or custom templates.

View Help:

gonectr create -h

Basic Usage: Create Project

gonectr create demo-project

This will create a basic Gone project named demo-project in the current directory.

Create Project with Specific Template

gonectr create demo-project -t template-name

List All Available Templates

gonectr create -ls

This command lists all built-in project templates with their brief descriptions.

Create Project with Module Name

gonectr create demo-project -t template-name -m github.com/gone-io/my-module

This is particularly useful when creating projects that will be published as public packages.

Create Project from Remote Git Repository Template

gonectr create demo-project -t https://github.com/gone-io/template-v2-web-mysql

You can directly use any Git repository that follows the Gone template specification as a project template.

2. install Command: Install Gone Modules and Generate module.load.go

The install command integrates Gone modules into your project and automatically generates the necessary loading code.

Gone Module Best Practice: We recommend each Gone module to provide one or more gone.LoadFunc functions, such as:

func Load(gone.Loader) error {
    // Load related Goners
    return nil
}

View Help:

gonectr install -h

Basic Usage: Install Module

gonectr install demo-module

This adds demo-module to your project and generates the corresponding loading code.

Specify LoadFunc

# Specify LoadA and LoadB functions for generating loading code
gonectr install module LoadA,LoadB

Real Example

gonectr install github.com/gone-io/goner/nacos RegistryLoad

This installs the nacos module and uses its RegistryLoad function for initialization.

Uninstall/Modify Module

When executing gonectr install module command:

• If the module is not installed, it will be installed
• If already installed, an interactive selection list will be displayed where you can uncheck unwanted LoadFunc to remove them from module.load.go

gone-io Official Modules, Supporting Short Names

gonectr install goner/nacos

Note: For unofficial modules, you need to use the complete Golang module name.

3. generate Command: Generate *.gone.go Files for Gone Projects

The generate command scans project directories and automatically generates integration code files needed by the Gone framework.

Functionality

This command will:

1. Scan all packages in specified directories

2. Create init.gone.go file for packages containing Goner or LoadFunc, generating automatic loading code:

   func init() {
       gone.
           Loads(Load).  // Load LoadFunc
           Load(&MyGoner{})  // Load Goner
           // ... Load more Goners
   }
   

   Note: If a package defines LoadFunc, it will only load LoadFunc and not directly load Goners, indicating that the user has chosen to manually manage Goners.

3. Create import.gone.go file in the main package directory to import all discovered Goner packages:

   package main
   
   import (
       _ "test"
       _ "test/modules/a"
       _ "test/modules/b"
   )
   

Important: Do not manually modify *.gone.go files, as they will be automatically overwritten by gonectr.

Specify Scan Directory

# Can specify multiple directories simultaneously
gonectr generate -s ./test -s ./test2

Specify Main Function Directory

gonectr generate -m cmd/server

Advanced Usage: Generate import.gone.go for Non-main Package

gonectr generate -m for_import --main-package-name for_import

Advanced Usage: Support Multiple Gone Instances

When using multiple Gone instances in the same program, you can use --preparer-code and --preparer-package parameters:

# Goners in gone1 directory use instance-1 instance
gonectr generate -s gone1 --preparer-code 'g.App("instance-1")' --preparer-package 'github.com/gone-io/goner/g'

# Goners in gone2 directory use instance-2 instance
gonectr generate -s gone2 --preparer-code 'g.App("instance-2")' --preparer-package 'github.com/gone-io/goner/g'

Use with go generate

Create a generate.go file in the project root directory and add the following code:

//go:generate gonectr generate -m main-package-dir

Then execute go generate ./... to automatically run the gonectr command.

4. mock Command: Generate Mock Code

The mock command generates Mock implementations for interfaces and registers them as Goners, facilitating integration into the Gone framework for testing.

Prerequisites: This feature depends on the uber mockgen tool, please install it first:

go install go.uber.org/mock/mockgen@latest

View Help:

gonectr mock -h

Basic Usage

# Generate Mock implementation for UserService interface in service package
gonectr mock -package service -interfaces UserService

More Options

# Generate Mock implementations for multiple interfaces and specify output directory
gonectr mock -package service -interfaces "UserService,OrderService" -output ./mocks

5. build Command: Build Gone Projects

The build command is an enhanced wrapper around the standard go build, specifically designed for Gone projects.

Features

• Automatically executes go generate ./... before compilation to ensure all auxiliary code is updated
• Supports all standard go build parameters and options

View Help:

gonectr build -h

Basic Usage

# Build Gone project in current directory
gonectr build

# Specify output filename
gonectr build -o myapp

# Use other go build parameters
gonectr build -v -ldflags="-s -w"

6. run Command: Run Gone Projects

The run command is similar to build, serving as an enhanced wrapper around go run.

Features

• Automatically runs go generate ./... before execution to update all auxiliary code
• Supports all standard go run parameters and options

View Help:

gonectr run -h

Basic Usage

# Run Gone project in current directory
gonectr run

# Run specific file
gonectr run main.go

# Run with parameters
gonectr run . -config=dev.yaml

FAQ

Q: What is the relationship between gonectr and standard Go tools?

A: gonectr is a complement to standard Go tools, specifically designed for the Gone framework. It simplifies Gone-specific code generation and project management processes but still internally calls standard Go commands.

Q: How to upgrade gonectr to the latest version?

A: Execute go install github.com/gone-io/gonectr@latest to update to the latest version.

Q: Should *.gone.go files be included in version control?

A: It's recommended to include these files in version control as they are part of the project structure. However, they can also be dynamically generated in CI/CD pipelines.

More Resources

• Gone Framework Official Documentation
• Gone Project Templates List
• Issue Feedback