Hello everyone! The much-anticipated GoFrame v2 version has finally been released! This version includes a large number of improvements and new features, as well as some groundbreaking functionalities.

From last summer to this spring, we have worked hard all the way, and we hope everyone is satisfied.

Thanks to all community partners for their contributions and support from community friends!

In the new year, we continue to stay grounded, never forgetting our original intention!

Upgrade Guide: Happily Upgrade from v1 to v2

1. Important Features

1. New Engineering Design

  • More rigorous and standardized
  • Standardization of naming style
  • Standardization of pointers and value passing parameters
  • Further simplified, improving development efficiency
  • New version development tools support the accurate implementation of engineering specifications
  • Entity/DAO/DO features
  • Interface-oriented design
  • More detailed introduction: Engineering Design 🔥
  • Observability further: bold foresight and determination
  • The framework enables OpenTelemetry features by default
  • The framework creates TraceID by default, according to OpenTelemetry generation standards
  • All core components of the framework support link tracing information transmission
  • The logging component supports printing link information
  • More detailed introduction: OpenTelemetry Tracing

3. Standardized Route Registration Features

  • Standardized API structured programming design
  • Standardized API interface method parameter style definition
  • Simplified route registration and maintenance
  • Unified interface return data format design
  • Automatic API parameter object reception and validation
  • Automatically generates interface documentation based on the standard OpenAPIv3 protocol
  • Automatically generates SwaggerUI page
  • More detailed introduction: Standard Router

4. Full Error Stack Feature

  • A major decision made at the framework level
  • All framework component errors support error stacks
  • Detailed introduction: Error Stack

5. New Error Code Feature

  • Uses interface design, highly extensible
  • Provides selectable common error codes
  • Core component base layer of the framework has enhanced error code support, e.g., identifying if DB execution error through error code in error
  • More detailed introduction: Error Handling - Error Code

6. Component Interface Design

  • Top-down unified interface design
  • Core components all use interface design
  • Higher extensibility and customizability
  • More detailed introduction: Interface and Generic

7. Support for Generic Framework

  • What is the framework gvar generic?
  • Extensive use of gvar generic in core components of the framework
  • The significant value of gvar generic in the framework
  • Why it is not recommended to use generics in top-level business
  • More detailed introduction: Interface and Generic

8. Plenty of ORM Improvements

9. Other Important Improvements

1) Logging Component Handler Feature

  • Middleware design
  • Supports multiple Handler processing
  • Provides more flexible and powerful support for developer-defined log processing
  • More detailed introduction: Logging - Handler

2) Logging Component Color Printing

  • Default color printing output in terminal
  • Different colors for different levels by default, configurable
  • Output to file/custom Writer default off, can be turned on via configuration
  • More detailed introduction: Logging - Color Printing

4) Improved Debug Mode Introduction

2. Function Improvements

1. Data Components

  1. /database/gdb

  2. Deprecated Table method, unified use of Model method to create Model object.

  3. Deprecated Struct/Structs methods in Model, unified use of Scan method to execute query results conversion to Struct object/objects array: Model Query - Scan

  4. Deprecated BatchInsert/BatchReplace/BatchSave methods, unified use of Insert/Replace/Save methods for implementation, internally auto-recognizing parameter type to decide single or batch write: ORM Model - Insert/Save

  5. Added DoFilter interface method for custom filtering of SQL&Args before ORM submits to underlying driver: ORM Interface - Callback

  6. Added DoCommit interface method for custom processing before ORM submits SQL&Args to underlying driver

  7. Added ConvertDataForRecord interface method for customized data conversion handling. ORM Interface - Callback

  8. Added Raw method to build Model object through raw SQL statement, followed by using Model chaining operations and features: ORM Model - Model

  9. Added Handler feature for customized Model object modification and returning new Model object, allowing easy reuse of common logic: ORM Model - Handler

  10. Added Union/UnionAll feature for merging results of multiple SQL/Model queries: Model Query - Union/UnionAll

  11. Added With feature for condition query and sort statement configuration support: Model Association - With

  12. Added OnDuplicate/OnDuplicateEx methods for specifying update/do-not-update field of Save methods: ORM Model - Insert/Save

  13. Added Wheref/WhereOrf methods for condition passing with formatted string statement: Model Query - Where

  14. Added WhereLT/WhereLTE/WhereGT/WhereGTE and WhereOrLT/WhereOrLTE/WhereOrGT/WhereOrGTE methods for adding common comparison conditions to ORM.

  15. Added WherePrefix/WhereOrPrefix methods for adding table prefixes to condition fields, commonly used in association queries

  16. Added FieldsPrefix/FieldsExPrefix methods for adding custom table prefix to query fields, commonly used in association queries

  17. Added FieldsCount/FieldsSum/FieldsMin/FieldsMax/FieldsAvg methods for adding common unified query conditions

  18. Added LeftJoinOnField/RightJoinOnField/InnerJoinOnField methods for convenient association with tables having the same field name

  19. Added OmitEmptyWhere/OmitEmptyData methods for specifically filtering empty value data in Where conditions and Data: ORM Model - Fields Filtering

  20. Added OmitNil/OmitNilWhere/OmitNilData methods for specifically filtering nil data in Where conditions and Data: ORM Model - Fields Filtering

  21. Added TimeZone configuration item for custom time zone conversion in database queries (currently supports mysql/pgsql): ORM - Configuration

  22. Improved Cache feature, supports accurate cache parameter control

  23. Added Close method for manually closing database connection

  24. Removed ORM configuration limit of default 100 connections when custom configuration not used.

  25. Improved time maintenance feature, no longer automatically filtering CreatedAt/UpdatedAt/DeletedAt related parameters submitted by developers, allowing custom updates to related time fields in ORM operations.

  26. Improved database execution SQL log recording, added affected row count recording

  27. Interface method HandleSqlBeforeCommit renamed to DoCommit.

  28. Database method operations uniformly added context.Context as the first required parameter.

  29. Fixed gdb component With feature multi-level query invalid issue.

  30. Removed all deprecated methods of query result types Record/Result.

  31. Completed unit tests.

  32. /database/gredis

  33. Adopted adapter pattern, refactored the component with interface design to improve extensibility: Redis - Interface

  34. Provided default adapter implementation based on third-party goredis package, added support for Redis cluster: Redis - Configuration

  35. Due to support for cluster features, configuration file format changed: Redis - Configuration

2. Network Components

  1. /net/ghttp
  2. New route registration method: Standard Router
  3. Default Request object injection into ctx context object, with added RequestFromCtx/g.RequestFromCtx methods to obtain Request object in ctx.
  4. Abstracted and encapsulated Client features into gclient component: HTTPClient
  5. Server logs added support for printing ctx context link information and improved log format: Link Tracing
  6. Parameter acquisition returns unified use of *gvar.Var generic object.
  7. Deprecated direct operation methods of HTTP Client in ghttp, must create Client object for client access operations.
  8. Deprecated Controller route registration method, removed related implementation code.
  9. /net/gtrace
  10. Upgraded go.opentelemetry.io/otel to the latest official version.
  11. Improved new link tracing usage documentation: Service Tracing

3. System Components

  1. /os/glog
    1. To promote observability features and implement link tracing specifications, all log printing methods added context.Context parameter.
    2. Logging component added Handler feature, using middleware design and supporting multiple Handler processing, providing more flexible and powerful support for developer-defined log processing: Logging - Handler
    3. Logging component added support for color printing of content, default color printing output in terminal, output to file/custom Writer default off, can be enabled via related configuration: Logging - Color Printing
    4. Deprecated Println method.
    5. Documentation update: Logging
  2. /os/gres
    1. Added Export method for exporting files from resource component to local disk: Resource - Methods
  3. /os/gfile
    1. Added SizeFormat method for getting formatted size string of specified file.
    2. Documentation update: File
  4. /os/gcache
    1. Adopted adapter pattern, refactored the component with interface design to improve extensibility: Caching - Interface
    2. Provided default cache implementation based on process memory: Caching - In-Memory
    3. All operation methods added context.Context context parameter.
    4. Parameter acquisition returns unified use of *gvar.Var generic object.
    5. Added Must* methods for directly obtaining parameters and triggering panic on errors.
  5. /os/gcfg
    1. Adopted adapter pattern, refactored the component with interface design to improve extensibility: Configuration - Interface
    2. Provided default configuration management based on file system: Configuration
    3. Parameter acquisition returns unified use of *gvar.Var generic object.
    4. All operation methods added context.Context context parameter.
    5. Added GetWithEnv method, automatically reading corresponding parameters from environment variables when they cannot be found in configuration adapter: Configuration Management - Configuration Reading
    6. Added GetWithCmd method, automatically reading corresponding parameters from command line parameters when they cannot be found in configuration adapter: Configuration Management - Configuration Reading
    7. Added Must* methods for directly obtaining parameters and triggering panic on errors.
    8. Configuration component usability improvement, accessing configuration component via singleton object will automatically search configuration files according to toml/yaml/yml/json/ini/xml file suffix: Configuration
  6. /os/gcmd
    1. Parameter acquisition returns unified use of *gvar.Var generic object.
    2. Brand new multi-level command line management method, supports automatic generation of command line usage tips: Command - Object
    3. Added object-based command line management method, more suitable for large terminal command scenes: Command - Structure
  7. /os/genv
    1. Parameter acquisition returns unified use of *gvar.Var generic object.
  8. /os/gcron
    1. Added context.Context parameter to defined scheduled task methods.
    2. Added context.Context parameter to all create scheduled task methods.
    3. Documentation update: Cron Job
  9. /os/gtime
    1. Deprecated Second/Millisecond/Microsecond/Nanosecond package methods, replaced with Timestamp/TimestampMilli/TimestampMicro/TimestampNano methods.
    2. Documentation update: Time
  10. /os/gtimer
    1. Added context.Context parameter to defined timer methods.
    2. Added context.Context parameter to all create timer methods.
    3. Improved the timer task execution detection mechanism based on priority queue data structure storage, enhancing execution performance.
    4. Documentation update: Timer
  11. /os/grpool
    1. Added context.Context parameter to callback method definitions.
    2. Added context.Context parameter to goroutine pool task addition methods.
    3. Documentation update: Coroutine Management - grpool
  12. /os/gsession
    1. Added ctx context parameter input to gsession.Storage interface for receiving context information and implementing complete link tracing. For rigor, added error return parameter: Session
    2. Parameter acquisition returns unified use of *gvar.Var generic object.
  13. /os/gview
    1. Added context.Context parameter to template parsing methods.
    2. Added plus/minus/times/divide arithmetic template methods.
    3. Documentation update: Template Engine
  14. /os/gstructs
    1. Opened structs package from internal of framework, named as gstructs, used for advanced usage of struct reflection operations: Object Information

4. Error Handling

  1. /errors/gerror

  2. Added Message method for obtaining error message of specified error code.

  3. Added CodeMessage method for obtaining error code information of specified error.

  4. Added NewOption method for custom-configured error object creation, dedicated to advanced players of the framework.

  5. Added HasStack method to determine whether given error interface object has implemented (contains) stack information.

  6. Changed error code from integer to interface object to achieve customizability and improve extensibility, refer to gcode component introduction for details: Error Code - Example

  7. Improved usability, revised NewCode/NewCodeSkip/WrapCode/WrapCodeSkip methods, optional text input parameter, default using Message info of corresponding error code.

  8. /errors/gcode

  9. Added gcode error code component, providing highly customizable and extensible error code management, combined with gerror component for powerful error handling: Error Code - Example

5. Other Components

  1. /container/garray
  2. Added At method to each array type for directly obtaining returned data at specific index position.
  3. Documentation update: Array - Methods
  4. /debug/gdebug
  5. Added TestDataContent method for directly obtaining file content of specified path under testdata directory in testing package.
  6. Documentation update: Debugging
  7. /encoding/gjson
  8. Deprecated most Get* methods, unified use of Get method to obtain the content of specified pattern, uniformly returns *gvar.Var generic object, developers can use corresponding methods to easily convert to specific type variables according to business scenario.
  9. Added several Must* methods.
  10. Comprehensive update on usage documentation
  11. /frame/g
  12. Added ModelRaw method for conveniently creating native SQL based database Model object.
  13. Added logger configuration to ORM objects created via /frame/g module, auto-initialized by automatically reading configuration files: ORM - Configuration
  14. Added logger configuration to Server objects created via /frame/g module, auto-initialized by automatically reading configuration files: Configuration
  15. /frame/gmvc
  16. Deprecated gmvc coupled module, no further support in the future.
  17. /util/gutil
  18. Improved implementation of Dump method, no longer using json package to implement type printing, instead self-implemented feature for printing any type, supporting detailed data type printing: Utility Functions
  19. Added SliceToMapWithColumnAsKey method for converting Slice to Map according to certain rules.
  20. /utils/gvalid
  21. Added bail validation rule, and Bail chaining method for immediately exiting validation when data validation fails and not executing subsequent validation rules.
  22. Added datetime validation rule for validating common date and time types, with date separator supporting only -, format like: 2006-01-02 12:00:00.
  23. Removed package validation methods, unified implementation of data validation using chaining operations.
  24. All validation methods added context.Context parameter.
  25. Brand new, highly complete usage documentation of the data validation component: Data Validation

For other numerous improvement details, we won’t elaborate here. Interested friends can refer to the official website goframe.org

3. CLI Toolchain

  1. Refactoring implemented with the encapsulation of the brand new gcmd command line object.
  2. Improved init command, supports SingleRepo/MonoRepo two repository initialization. Project initialization no longer depends on remote repository.
  3. Improved gen dao command, adopting the brand new V2 engineering design, automatically generating entity/dao/do code files.
  4. Removed update command, tool updates unified through https://github.com/gogf/gf/tree/master/cmd/gf
  5. Removed get command.
  6. All-new documentation: CLI Tool