DOCSEARCHbyAlgolia
Submit Docs

ruoyi-go Framework

repository·main·Indexed 42 days ago

https://github.com/lostvip-com/ruoyi-go

A lightweight, fast-development framework written in Go for small to medium-sized projects. It features a Spring Boot-inspired architecture, SQL/Go separation using GORM and _mapper.sql files, and built-in system management. Core components include Gin for the web layer, Redis for caching, and lv-framework for configuration, logging, and database utilities. It supports environment variable interpolation in YAML and automatic SQL query construction via struct search tags.

Tokens
10.9K
Snippets
28
Records
43
Agent score
54%

What's inside ruoyi-go

  1. Overview of lv-framework

    main

    lv-framework is a lightweight, rapid development framework for the Go programming language. It is designed for small to medium-sized projects, prioritizing simplicity and avoiding excessive encapsulation.

    Key characteristics include:

    • Spring Boot-inspired structure: The project structure mimics Spring Boot, making it easy for Java developers to transition and allowing it to be registered in Nacos as a Spring Cloud microservice component.
    • SQL/Code Separation: It supports a MyBatis-like approach where SQL is separated from Go code. This is implemented using gorm combined with Go template syntax. To ensure IDEs recognize SQL keywords, SQL files should use the _mapper.sql suffix.
    • Environment Variable Interpolation: Similar to Spring Boot, you can use expressions in YAML configuration files to pull values from environment variables, facilitating easy switching between production, development, and testing environments.

  2. Core Technologies and Components

    main

    ruoyi-go is built using a modern Go stack:

    • Web Framework: Gin (supports hot-reloading templates).
    • ORM/DAO: GORM (supports namedSQL placeholders and SQL/Go separation via _mapper.sql files).
    • Caching: Redis.
    • Security: Supports stateless JWT or stateful Token authentication.
    • API Documentation: Generated via Swaggo/swag.
    • Excel Export: Uses tealeg/xlsx.
    • Frontend: Server-side rendering with template engines and RuoYi v4.7.0 components.

  3. Understand the ruoyi-go project structure

    main

    The project follows a simplified structure designed for ease of use, mimicking some aspects of SpringBoot.

    • main/: The entry point of the application.
      • modules/: Contains business logic modules.
        • system/: Core system module.
          • internal/: Source code that cannot be imported by other modules.
          • mapper/: MyBatis-style SQL mapping files (using _mapper.sql suffix).
          • bootstrap.yml & application.yml: Configuration files.
      • pkg/: Third-party and framework-level components.
        • lv_framework/: Core framework modules including lv_cache, lv_conf, lv_db, lv_log, lv_utils, and lv_web.
    • bak/: Backups for local configs, scripts, and SQL files.
    • go.work: Go workspace configuration.

  4. Use environment variables in YAML configuration

    main

    You can use the ${VARIABLE_NAME:DEFAULT_VALUE} syntax within your YAML configuration files to inject environment variables. This is useful for managing hostnames, ports, and credentials across different environments.

    Example syntax:

    host: ${REDIS_HOST:lostvip.com}

    If the environment variable REDIS_HOST is set to 192.168.88.114, the configuration will use that value. If not set, it defaults to lostvip.com.

  5. Core technologies and components in lv-framework

    main

    The framework is built upon several industry-standard technologies:

    • DAO Layer: Powered by gorm, supporting named SQL placeholder queries.
    • Web Framework: Powered by Gin, offering high efficiency and hot-reloadable templates.
    • Frontend: Uses template engines and server-side rendering (SSR).
    • Caching: Supports redis and RAM-based caching.

  6. Configure SQL joins using search tags

    main

    You can perform SQL joins by embedding a struct that contains a search tag defining the join type, the join condition (on), the target table, and the relationship to the primary table (join).

    Example tag format: search:"type:left;on:id:receipt_id;table:receipt_goods;join:receipts"

    • type: The join type (e.g., left).
    • on: The join condition in the format local_column:remote_column.
    • table: The table to join.
    • join: The base table/relationship context.
    type TestJoin struct {
	PaymentAccount string `search:"type:icontains;column:payment_account;table:receipts" form:"payment_account"`
}

// In the parent struct:
// TestJoin `search:"type:left;on:id:receipt_id;table:receipt_goods;join:receipts"`

  7. Use Search tags for SQL query construction

    main

    The lv_sql utility allows you to define SQL search criteria directly within struct tags using the search key. This enables automatic generation of complex SQL queries (including joins, filters, and sorting) based on struct definitions.

    To use this, define your query struct with tags specifying the type of comparison, the database column, and the target table. You can also define join logic and ordering within the same struct hierarchy.

    type ApplicationQuery struct {
	Id       string    `search:"type:icontains;column:id;table:receipt" form:"id"`
	Domain   string    `search:"type:icontains;column:domain;table:receipt" form:"domain"`
	Version  string    `search:"type:exact;column:version;table:receipt" form:"version"`
	Status   []int     `search:"type:in;column:status;table:receipt" form:"status"`
	Start    time.Time `search:"type:gte;column:created_at;table:receipt" form:"start"`
	End      time.Time `search:"type:lte;column:created_at;table:receipt" form:"end"`
	TestJoin `search:"type:left;on:id:receipt_id;table:receipt_goods;join:receipts"`
	ApplicationOrder
}

type ApplicationOrder struct {
	IdOrder string `search:"type:order;column:id;table:receipt" form:"id_order"`
}

type TestJoin struct {
	PaymentAccount string `search:"type:icontains;column:payment_account;table:receipts" form:"payment_account"`
}

  8. Quickstart: Install and Run ruoyi-go

    main

    To get started with ruoyi-go, follow these steps to set up your environment and launch the application.

    Prerequisites

    Set your GO_PROXY environment variable to ensure dependencies are installed correctly:

    export GO_PROXY=https://goproxy.cn

    1. Configure Database and Cache

    • SQLite: The project uses SQLite by default. No configuration changes are required.
    • MySQL: Import the SQL files located in the docs directory, then update the connection details in application.yml.

    2. Launch the Application

    Navigate to the main directory and use one of the following methods:

    Option A: Standard Run

    cd main
go run main.go

    Once started, the application will print the access URL (e.g., http://127.0.0.1:8080).

    Option B: Hot Reloading (Development) Install the fresh tool to enable hot reloading:

    go get github.com/pilu/fresh
go install github.com/pilu/fresh

# Then run:
fresh
    cd main
go run main.go

  9. Cross-compile for multiple platforms

    main

    You can use xgo to cross-compile the project for various platforms. It is recommended to pull the techknowlogick/xgo Docker image for this purpose.

    Compile for all platforms:

    xgo -ldflags "-w -s"

    Compile specifically for arm7 (Linux):

    xgo -ldflags "-w -s" -out svc-$(date '+%Y%m%d_%H%M%S') --targets=linux/arm-7 .
    xgo -ldflags "-w -s"